The options array format
The first thing you need to know, therefore, is what categories or classifications of options you can use.
The framework sees options as falling into the following categories:
Accordingly, each row in the Options array contains the following information:
User Options array storage
The application object has two methods, ApplyUserGlobalOptions( ) and ApplyUserOptsForSession(toForm), it uses to bring these settings into the current environment. Each of these methods simply loops through the array and fires off statements for its option type (global or session).
The use of SET-type items, whether global or local to a data session, is straightforward (SETs are issued at the appropriate time, and in the appropriate data session as necessary.)
The use of object-type items in these methods is only a little more complicated: the application object considers a "global object setting" as applying to itself (THIS) and a "datasession object setting" as applying to the form for which it was passed a reference. You can add qualified information into Column1 to set properties of an application member or form member as well, but this parental object reference to the application object or form object will precede it when one of these two Apply method fires off the statement.
The default _options dialog gives you good examples of how you might create options. It contains options of all the available type (global and local SETtings, application and form properties). It also is fairly sophisticated in the way it chooses to apply its set of known options. As you see in the figure below, you can apply the current choices in the dialog to the environment, or save them to the user's defaults, or save the current settings as a new set of defaults for this user, similar to what you can do with VFP's own options.
The default user options dialog has some good ideas and good examples built in, but this set of options is not mandatory.
However, you may wish to see a simpler example, just to see how the options work without distraction. I've prepared one for these notes, as a dialog class named MyOptions, which you'll find in the SUBAPP\NEWAPP.VCX.
Here's the situation in this simple example: The application framework uses an FFC component _FilterExpr, that provides the user with a chance to type a VFP expression. _FilterExpr allows the user to construct this expression, rather than typing it, in one of two modes, advanced and simple. In "advanced" mode _FilterExpr invokes the contents of the _GETEXPR system variable, but in "simple" mode, _FilterExpr invokes a tailored _FilterDialog, instead.
The application object has a property, lUse_GetExpr, that you, as developer, can use to indicate which mode _FilterExpr should use, when used within the framework application. However, you might prefer to make this a choice for your users, instead. Accordingly, you would create a user options array row that was global (because this is an application-wide setting) and applies to an object, rather than a SET (because this is an application property).
Below you see all the code I wrote for my simple MyOptions dialog. On startup, the dialog reads the current value of this application property:
* I'm not framework-enabling or anything, * and this dialog isn't based on any * framework specific class -- I'm just * using an explicit reference.. * this would be in your app.H file as: * #DEFINE APP_GLOBAL goApp THIS.oApp = goApp IF VARTYPE(THIS.oApp) # "O" RETURN .F. ENDIF LOCAL lvValue RESTORE FROM MEMO ; (THIS.oApp.cUserTableAlias+".UserOpts") ADDITIVE * the local array laOptions is now * available in this method * tell the application object to use this lvValue = THIS.oApp.GetUserOptionSetting("lUse_GetExpr", ; @laOptions) IF VARTYPE(lvValue) # "L" lvValue = .F. ENDIF * display it in the dialog: THIS.chklUse_GetExpr.Value = lvValue
When the user presses "OK" in this dialog, here's how the information is stored, both to the memo field as a saved default, and (in this simple example)to the current value at the same time:
LOCAL liSet, lcArray, laOptions FOR liSet = 1 TO 2 && set current, then set default, arrays: IF liSet = 1 lcArray = "THISFORM.oApp.aCurrentUserOpts" ELSE lcArray = "laOptions" ENDIF DIME &lcArray.[1,4] &lcArray.[1,1] = "lUse_GetExpr" &lcArray.[1,2] = THISFORM.chklUse_GetExpr.Value * application or application member property, not SET: &lcArray.[1,3] = .F. * set on a global level, not form/session private: &lcArray.[1,4] = .T. ENDFOR
* current: THISFORM.oApp.lUse_GetExpr = THISFORM.chklUse_GetExpr.Value * default: SAVE ALL LIKE laOptions TO ; MEMO (THISFORM.oApp.cUserTableAlias+".UserOpts")