Step 2: Adding Action Items

Last updated on: 1/27/2013 8:59 PM 
Created on: 11/2/2016 2:22 PM 

The System Core 7 framework allows an applet to add action items to various menu items throughout the framework. Action items are divided into two types of general actions: the creation of new data objects and the manipulation of existing data objects and any number of actions from either category can be created by using the Task List Extension Interface into System Core. It is important to note that the editing of existing data objects using the actions cut, copy, paste, rename and delete are handled by the framework and do not require any additional implementation. To begin creating action items for either the New menu or action items for the context menus, you need to subclass your existing derived Demo Applet class from the ISCTaskListExtension base class.

The framework allows any number of action items in either category to be created. The framework discovers all the available tasks an applet offers through the use of enumeration. Use the EnumNewOption() method to add one or more items to the New menu. Use the EnumTaskOption() method to add one or more items to a context menu. Both methods are pure virtual and must be implemented additionally both contain identical parameters. The first parameter in both methods is the enumeration index. This value will start at zero and indicates the numeric ID of the action being enumerated. When the user later selects an action, this ID will be the parameter to the trigger methods. Also note that there are four IDs that are reserved by the framework: FRW_TASK_ID_OPEN_APP, FRW_TASK_ID_EMAIL_ID, FRW_TASK_ID_MANAGE_IDS and FRW_TASK_ID_DEVICE_PROPS. Of these four reserved IDs, only the FRW_TASK_ID_OPEN_APP can be used by Application Type Applets and is only supported in the EnumTaskOption() method.

Both enumeration methods contain four additional parameters in common. The strText parameter must contain the textual string presenting the action to the user. Likewise, strResource should contain the string resource ID or resource URL of the visual image of the task presented to the user. The next parameter in common is the ulFlags bitmask. The bits set in this mask are important to check as they indicate where in the framework the action is being displayed. The following table describes the meaning behind these bits:

Two additional flags are set indicating the size of the images the framework seeks for display: ETF_LARGE_IMAGES and ETF_EXTRA_LARGE_IMAGES. The ISCTaskListExtension base class contains a method GetResourceBase() which can be called to obtain the proper resource folder/URL information based on the presence of either of these flags.

The final parameter common to both enumeration methods is nViewID. In most all cases this value will be MWVID_NONE, unless the ETF_CONTEXT_MENU flag is set the nViewID will contain a Main Window View ID for the main window component that has the input focus. Using both the ulFlags and nViewID parameters allows the applet developer to present the correct available actions given the user's current location in the framework.

The EnumTaskOption() method contains the nCmdID parameter. In earlier versions of SC, the main desktop window menu could have the text of menu items customized to reflect a better description of what action selecting the menu item would perform. For example, the File...Open menu item could be customized to instead read File...Import. With System Core 7 that API for customization has been removed as in many cases task items implement the same functionality. To have the task's description replace the text of a standard menu item, set the nCmdID parameter to a valid Custom Menu Field flag. This allows for File...Open to become File...Import by simply setting nCmdID to CMF_FILE_OPEN. Note that when the nCmdID parameter returns a valid standard menu item, the event trigger for that menu item is invoked instead of this interface's OnTask trigger. For this reason and for the consideration of the ETF_CONTEXT_MENU and EFT_TASK_WINDOW conditions, it is recommended that this interface be considered in conjunction with the ISCAppletWindowExtension interface. Also, the framework interprets the parameter values in a manner that would be native to the operating system. Therefore it is recommended not to use the nCmdID parameter if there is no ISCAppletWindowExtension as the task items then runs the risk of never being presented to the user. If a nCmdID must share a standard menu item, use extra care to ensure that the task action doesn't depend on any user interface components.

Finally the OnNewItem() and OnTaskItem() methods must be implemented. Like the enumeration methods, these too are pure virtual methods, thus even unused stubs must be provided in the applet. Both trigger methods take a single parameter which will contain the ID used to enumerate the action.

Now that these four methods of the ISCTaskListExtension have been implemented, our Demo applet can now display and execute its tasks within the framework.