The Clipboard: 3.2 Using The Clipboard: Managing the Edit Menu

3.1 Registering with the Clipboard | Next:

MSG_META_CLIPBOARD_NOTIFY_NORMAL_TRANSFER_ITEM_CHANGED, ClipboardTestItemFormat()

The Edit menu is simply a normal menu with several standard triggers. Most applications will simply include a GenEditControl object in their UI, add a menu GenInteraction of type GIGT_EDIT_MENU, and leave the Edit menu construction up to them (see The GenEditControl ). Some, however, may want to create their own menu and triggers. A sample of this type of setup is shown in A Sample Edit Menu .

Code Display 7-4 A Sample Edit Menu

/* Other objects, including a GenPrimary as the parent of the GenInteraction, are
 * left out for clarity. */

/* The GenInteraction is the menu in which the three triggers will appear. */
@object GenInteractionClass EditMenu = {
    GI_visMoniker = `E', "Edit";
    GI_comp = EditCut, EditCopy, EditPaste;
    GII_visibility = GIV_POPUP;
}

/* The Cut trigger sends a MSG_META_CLIPBOARD_CUT to the Process
 * object when pressed. */
@object GenTriggerClass EditCut = {
    GI_visMoniker = `t', "Cut";
    GTI_destination = process;
    GTI_actionMsg = MSG_META_CLIPBOARD_CUT;
}

/* The Copy trigger sends a MSG_META_CLIPBOARD_COPY to the
 * Process object when pressed. */
@object GenTriggerClass EditCopy = {
    GI_visMoniker = `C', "Copy";
    GTI_destination = process;
    GTI_actionMsg = MSG_META_CLIPBOARD_COPY;
}

/* the Paste trigger is set up initially disabled. It sends a
 * MSG_META_CLIPBOARD_PASTE to the Process object when pressed. */

@object GenTriggerClass EditPaste = {
    GI_visMoniker = `P', "Paste";
    GTI_destination = process;
    GTI_actionMsg = MSG_META_CLIPBOARD_PASTE;
    GI_states = @default & ~GS_ENABLED;
}

Some Edit menus may also contain other triggers such as "Delete Event," or "Remove Item." These triggers, however, are not standard and must be implemented exclusively by the application.

Two main rules govern the maintenance of the Edit menu:

The Cut and Copy triggers are enabled only when some data is selected that may be cut or copied from the document into the Clipboard.
The Paste trigger is enabled only when data in a pasteable format exists in the Clipboard's Transfer VM File.

The first rule must be implemented entirely by the application; the Clipboard will not enable or disable the Copy or Cut triggers. The second rule, however, requires that the application be notified whenever the Clipboard's contents change--it is possible, for example, for the application to copy data to the Clipboard, enable its Paste trigger, and have another application then also copy some custom data to the Clipboard. In this case, the original application must disable its Paste trigger if it can not read the data.

Whenever the Clipboard's contents change, the UI will send notification to all objects that have registered with it. The notification will be in the message MSG_META_CLIPBOARD_NOTIFY_NORMAL_TRANSFER_ITEM_CHANGED . Use of this message can be found in the ClipSamp sample application.

Code Display 7-5 Handling Clipboard Changes

/* MSG_META_CLIPBOARD_NOTIFY_NORMAL_TRANSFER_ITEM_CHANGED is sent with no
 * parameters and requires no return value. */

/* The strategy of this message is to first check whether the CIF_TEXT format, the
 * only format supported by this sample application, is available on the Clipboard.
 * If so, the Paste trigger is enabled; if not, the Paste trigger is disabled. */

@method MyClipProcessClass, MSG_META_CLIPBOARD_NOTIFY_NORMAL_TRANSFER_ITEM_CHANGED
{
    ClipboardQueryArgs			query;			/* A structure of arguments */
    Boolean			endisable = FALSE;			/* The trigger is disabled */

    /* Call ClipboardQueryItem() to gain exclusive access to and information about
     * the current transfer item. Pass it zero indicating we're checking the
     * normal transfer item (not the quick-transfer item) and the empty arguments
     * structure. */
    ClipboardQueryItem(TIF_NORMAL, &query);

    /* If there are any formats, then test if CIF_TEXT is one of them. The routine
     * ClipboardTestItemFormat() tests a format against all those available and
     * returns true if it is supported, false if it is not. Use the macro
     * FormatIDFromManufacturerAndType to create the format argument. If CIF_TEXT
     * is not supported, then the enDisable argument is set to TRUE. */

    if (query.CQA_numFormats) {
	if (ClipboardTestItemFormat(query.CQA_header,
		FormatIDFromManufacturerAndType(MANUFACTURER_ID_ME, CIF_TEXT))) {
	    endisable = TRUE;
	}
    }

    /* Because we've found out what we need to know, restore the Clipboard with a
     * call to ClipboardDoneWithItem(). This routine takes the transfer item's
     * header and returns nothing; it also relinquishes our exclusive
     * access to the Clipboard and is therefore very important. */

    ClipboardDoneWithItem(query.CQA_header);

    /* Now, if endisable is true, set the Paste trigger enabled. If endisable is
     * false, set it disabled. These operations are accomplished by sending the
     * appropriate message to the trigger object. */

    if (endisable) {
	@call EditPaste::MSG_GEN_SET_ENABLED(VUM_NOW);
    } else {
	@call EditPaste::MSG_GEN_SET_NOT_ENABLED(VUM_NOW);
    }
}

GEOS SDK TechDocs |

3.1 Registering with the Clipboard | Next:

3.3 The GenEditControl