3.1 Construct Controls on X-Function GUI

X-Function, Construct Controls on Dialog

Summary

This example demonstrates how to construct controls in an X-Function GetN dialog by TreeNode variable. This mechanism is used to avoid adding controls by multiple variables. This is an example X-Function dialog:

You will learn

1. How to create different controls by make_tree.
2. How to update a GUI on a specified control event.
3. How to check and ask for valid input.

Steps

1. Select Tools: X-Function Builder to open the X-Function Builder dialog, select File: New X-Function Wizard to create an X-Function with only one Input Variable named GUI of TreeNode type, and save it as gui_controls.oxf.
2. Open the X-Function in Code Builder, and add the following code into the gui_controls_make_tree function.

   if ( strcmp("GUI", lpcszVarName) == 0 ) // check variable by name
   {
   	// ID should be unique
   	int nBranchID = 0x0001;
   	int nUserID = GET_USER_DATAID(0); //NodeID to enable Theme support
   	
   	GETN_USE(tr)	//use this node as current node
   	
   	//begin of sub branch
   	GETN_BEGIN_BRANCH(UserInfo, "User Information")	GETN_ID(nBranchID++)
   		// string edit box
   		GETN_STR(UserName, "Name", "Unknown") GETN_ID(nUserID++)
   		
   		// pass word edit box
   		GETN_PASSWORD(Password, "Password", "") GETN_ID(nUserID++)
   	GETN_END_BRANCH(UserInfo) //end of sub branch
   	
   	//begin of sub branch
   	GETN_BEGIN_BRANCH(Detail, "Details") GETN_ID(nBranchID++)	
   		// editable drop-down list
   		GETN_STRLIST(Language, "Language", "English", "|English|German") 
   		GETN_ID(nUserID++)
   		
   		// radio buttons
   		GETN_BEGIN_BRANCH(lGender, "Gender") GETN_ID(nBranchID++)
   			GETN_RADIO_INDEX(Gender, 0, "Male|Female") GETN_ID(nUserID++)				
   			// the format of radio buttons	
   			GETN_OPTION_DISPLAY_FORMAT(DISPLAY_EDITOR_LEFT) 			
   		GETN_END_BRANCH(lGender)
   		
   		//numeric edit box, age must be Integer, so use format "%d"
   		GETN_NUM(Age, "Age", 18) GETN_OPTION_NUM_FORMAT("%d")
   		GETN_ID(nUserID++)
   		
   		//check box with event handling function
   		GETN_CHECK(iEmail, "Have Email", 0)	GETN_ID(nUserID++)//check box
   			GETN_OPTION_EVENT(_show_email) //event of iEmail checkbox
   		
   		// string edit box
   		GETN_STR(Email, "Email", "") GETN_ID(nUserID++)		
   	GETN_END_BRANCH(Detail) //end of sub branch
   }

3. Add the following event handling functions after the line //put your own support static functions here.

   static bool _show_email(TreeNode& tr, int nRow, int nType, Dialog& Dlg)
   {
   	TreeNode trDetail = tr.GUI.Detail;
   	if ( !trDetail )
   		return false;
   	int nShow = trDetail.iEmail.nVal;
   	//if check, show, else hide.
   	trDetail.Email.Show = (nShow == 1);
   	return true;
   }
   
   static bool _check_email(LPCSTR lpcszEmail)
   {
   	string strEmail(lpcszEmail);
   	if ( strEmail.Count('@') != 1 ) 
   		return false; //should contains '@' and only one.
   	int nSep = strEmail.Find('@');
   	string strLeft = strEmail.Left(nSep);
   	string strRight = strEmail.Right(strEmail.GetLength() - nSep - 1);
   	if ( strLeft.GetLength() == 0 )
   		return false;
   	if ( strRight.GetLength() == 0 )
   		return false;
   	LPCSTR lpcszInvalid = "~!#$%^&*()+ -=|\\/><,`";
   	if ( strEmail.FindOneOf(lpcszInvalid) >= 0 )
   		return false;
   	return true;
   }

4. Add error checking code into the gui_controls_event1 function.

   if ( strcmp(lpcszNodeName, "Email") == 0 )
   {
       string strVal = trGetN.GUI.Detail.Email.strVal;
       if ( !_check_email(strVal) )
       {
           strErrMsg = "Invalid Email Address! Please correct it";
           //disable OK button, should not continue when there is error.
           bOKEnable = false;
       }
   }

5. X-Function, Update Control Value on DialogChange the return value from return false (default) to return true to force a GUI change.
6. In the X-Function body, we just print out the user settings by tree. Click the Compile button to compile and save changes.

   out_tree(GUI);

Run the X-Function

1. Run the gui_controls -d command in the Script Window.
2. Click the Have Email check box on the dialog, and an email edit box will display.
3. If you input an invalid email address to the email edit box, for example, type in abc, an error message will show on the bottom of the dialog and the OK button will be disabled.
4. Click OK. The setting tree will be outputted to the Script Window.