Generic UI Controllers: 7.3 Other Controllers: The Float Format Controller

| Up: GEOS SDK TechDocs | Up | Prev: 7.2 GenPageControlClass

Including the Float Format controller in your application allows the user to format FP numbers into any of the system-defined formats. The controller also allows the user to define his or her own formats.

The following messages, routines and data structures all manage arrays of system-defined and user-defined formats. If you include a Float Format controller, you will need to intercept these messages and call many of these routines.

Retrieving Parameters of the Current Entry

 FloatFormatGetFormatParamsWithListEntry(),  FloatFormatGetFormatParamsWithToken(),  FloatFormatGetFormatTokenWithName()

The Float Format controller routines use a FormatInfoStruc structure to hold information about a particular format. This structure is convenient to pass around to other float format routines. The Float Format controller contains one instance field, formatInfoStrucHan , that stores the handle to the current FormatInfoStruc , if one is being used by the controller.

Code Display 12-10 FormatInfoStruc

typedef struct {
	/*
	 * FIS_signature is used internally for error-checking.
	 */
	word		FIS_signature;
	/*
	 * These two entries store the user defined format array for the 
	 * controller to work on. This array is created by FloatFormatInit().
	 */
	FileHandle		FIS_userDefFmtArrayFileHan;
	VMBlockHandle 		FIS_userDefFmtArrayBlkHan;
	/*
	 * These two entries store the object block and format list chunk that the 
	 * controller resides in.
	 */
	word		FIS_childBlk;
	word		FIS_chooseFmtListChunk;
	/*
	 * FIS_features stores the features list of the controller.
	 */
	word		FIS_features;
	/*
	 * FIS_editFlag is -1 if we are editing a current user-defined entry and 0 
	 * if we are creating a new user-defined entry.
	 */
	byte		FIS_editFlag;
	/* FIS_curSelection stores the current selection in the format list. */
	word		FIS_curSelection;
	/* FIS_curToken stores the token of the selected item in the list. */
	word		FIS_curToken;
	/* FIS_curParams stores the FormatParams of the selected item. */
	FormatParams		FIS_curParams;
} FormatInfoStruc;

FloatFormatGetFormatParamsWithListEntry() fills in a FormatInfoStruc corresponding to the passed list entry position in the Float Format controller's dynamic list. The routine must be passed a FormatInfoStruc with the entry position in FIS_ curSelection already filled in. You must also have the FIS_ userDefFmtArrayFileHan and FIS_ userDefFmtArrayBlkHan filled in properly before calling this routine.

This routine is called whenever the user clicks on a new item, or whenever the dynamic list needs to retrieve new monikers for the list. You will also probably need to use this routine in your application code when intercepting many of the Float Format controller messages.

FloatFormatGetFormatParamsWithToken() fills in the FormatParams of a particular format entry when passed a format's token. The routine must be passed the FormatInfoStruc with FIS_ curToken already filled in. You must also have the FIS_ userDefFmtArrayFileHan and FIS_ userDefFmtArrayBlkHan filled in properly before calling this routine.

FloatFormatGetFormatTokenWithName() returns the format token of a particular format when passed its name (in a FormatInfoStruc ).

Initializing the UI

 MSG_FLOAT_CTRL_UPDATE_UI,  MSG_FLOAT_CTRL_REQUEST_MONIKER,  FloatFormatInit(),  FloatFormatInitFormatList()

FloatFormatInit() initializes a format array to serve as the storage space for user-defined formats. It must be passed the VM file handle to create the array within.

MSG_FLOAT_CTRL_UPDATE_UI is sent to the Float Format controller whenever the controller needs to perform a visual update. Your Float Format controller should intercept this message and call FloatFormatInitFormatList() .

FloatFormatInitFormatList() initializes the Float Format dynamic list whenever the list needs to display a new moniker. It extracts the moniker text of the selected format from the FormatInfoStruc structure. Make sure that this structure has the proper VM file and block handles filled in prior to calling this routine.

MSG_FLOAT_CTRL_REQUEST_MONIKER is sent to the Float Format controller whenever it needs to display the text within the controller's dynamic list. To extract the current format's moniker, intercept this message and call FloatFormatGetFormatParamsWithListEntry() . You can then pass the format's textual name (from FIS_ curParams .FP_ formatName ) to MSG_GEN_DYNAMIC_LIST_REPLACE_ITEM_TEXT.

Setting Up Selected Formats

 MSG_FLOAT_CTRL_FORMAT_SELECTED,  FloatFormatProcessFormatSelected()

MSG_FLOAT_CTRL_FORMAT_SELECTED is sent to the Float Format controller whenever the user makes a new selection. This message allows your application to set up a new FormatInfoStruc based on the new selection. Your handler for this message needs to call FloatFormatProcessFormatSelected() .

User Defined Format Creation

 MSG_FLOAT_CTRL_USER_DEF_INVOKE,  FloatFormatInvokeUserDefDB(),  MSG_FLOAT_CTRL_USER_DEF_OK,  FloatFormatUserDefOK()

MSG_FLOAT_CTRL_USER_DEF_INVOKE is sent to the Float Format controller whenever the user has defined a new format and wishes to add it to the controller's dynamic list. Your handler for this message should call FloatFormatInvokeUserDefDB() in turn. If the user attempts to create a new format when MAX_FORMATS already exist, the routine will invoke an error box.

MSG_FLOAT_CTRL_USER_DEF_OK is sent to the Float Format controller to check whether the user-defined format is legal or previously duplicated. Your handler for this message should call FloatFormatUserDefOK() to perform this check and apply the user-defined format to the list of format entries if it is successful.

Deleting Formats

 MSG_FLOAT_CTRL_FORMAT_DELETE,  FloatFormatDelete()

MSG_FLOAT_CTRL_FORMAT_DELETE is sent to the Float Format controller when the user attempts to delete a user-defined entry. Your handler for this message needs to call FloatFormatDelete() .

Applying Formats

 MSG_FLOAT_CTRL_FORMAT_APPLY

MSG_FLOAT_CTRL_FORMAT_APPLY is sent to the FloatFormat controller when the user attempts to apply a format selected in the controller to the appropriate text selection. Your handler will need to extract information from the FormatInfoStruc and call the appropriate text formatting routine (e.g. FloatFloatToAsciI() ).

| Up: GEOS SDK TechDocs | Up | Prev: 7.2 GenPageControlClass