XSdk Assistant System
alpha version, October 2000
The task of creation new projects is made as easy as possible in the XSdk. Actually, the XSdk system contains a quite generic "application generator", which can prepare the project skeleton based on programmer's needs. For expressing those needs easy-to-use and intuitive GUI assistant panels are used. That is why there is currently not a support for the assistant system for a command-line based XSdk releases (we shall add it to future XSdk versions, so as all the ports offer equal services).
Therefore, you would seldom use some of the example projects as a template, for making a new one is in most cases more convenient.
Contents
- The Generic Assistant Frame describes the common panel, used by all the assistants, and its standard controls;
- For those who want to know the underlying mechanism so as they can eg. write their own templates, it is described in the Template system.
All the assistants use a common panel with a number of standard tools. It looks more or less like this:
From the top left corner to the right and bottom, there are the following controls:
- The API radio button allows you to decide whether the extended XSdk API should be used, or whether the plain Symbian API is sufficient. The extended API is ways better, allowing you to use a true object model even in the C++, and offering luxury class libraries, supporting visual programming and much more.
- The human language pop-up button selects the default human language for the project. See the localization support for more details.
- The assistant icon opens the appropriate help file.
- The pop-up list below the API radio button contains all the templates for the given project type. Often there will be just one, with the other assistant panel controllers sufficient for the customization; though, there are cases when utterly different projects of some type can be made. A good example might be the EXE file: a console-based executable differs from a GUI-based executable so much that it is better to use different templates, and not just customization inside one template.
- The main view area, gray on the picture, normally contains the particular template's customization controls. See eg. the application assistant for an example.
- The items in the programming language radio buttons by the right edge of the window are automatically enabled, based on the languages for which there are template files. If more of them are enabled, you can select the preferred main language.
Note that you can freely mix languages in one project in the XSdk! The option does not limit the project to the selected langauge; it only chooses the one in which the project will be generated. You then always can add new sources to any project in any supported programming language. - The info pane below the main view contains just a short information of the selected template.
- Finally, meaning of the two buttons in the bottom right corner should be obvious :)
Firstly it should be pointed out that you do not need to know the template system: quite the contrary, it is designed to serve you through the GUI panels, as simple and intuitive way as possible. Therefore, unless you really want to know how the template system is implemented, you do not need to read the rest of this document!
There are two reasons we document the template system at all:
- Primarily, it is quite probable you might want to add some templates of your own, making so the task of preparing projects of some generic types, used in your company, a child's game;
- Besides, we are aware this is an alpha release of the XSdk; therefore, though we do our best to the contrary, there are bugs and unfinished items between the templates. With this documentation, you can fix some problem yourself (do please send us the fixes to <xsdk@ocs.cz>).
Information placement
Almost all the template-relevant information is placed in each project type's Resources folder, inside its AssistantTemplates subfolder.
A few information with project-wide scope is also put into the standard project type's Info.table (which lays directly in the Resources folder).
The placement of the project types themselves depends on the host operating environment. Of the currently supported ones,
- Mac OS X Server keeps all the XSdk project types in /Local/Developer/ProjectTypes;
- Mac OS X public beta does not support the local library, so the project types mus be placed into the generic /Developer/ProjectTypes;
- WebObjects for NT place the files to c:/Apple/Local/Developer/ProjectTypes;
- since Linux features the "ProjectBuilderless" command-line XSdk, there are no project types there at all.
Info.table contents
Currently the only entry of the Info.table relevant for the template system is a list of default UID values. There is an array value in the Info.table for key "XSdkUIDSetting". The array must contain exactly three items, corresponding to the UID1, UID2, and UID3. The available values are:
- any number (can be expressed either decimally, or as a 0x<hexadecimal>, or even as a <hexadecimal>h, but in this case the number must begin by a decimal digit). If so, it is the fixed value for the appropriate UID;
- any string (which does not begin by a decimal digit). In this case, a temporary UID will be allocated when the project is created (see the UID management); it will be changeable through the project inspectors (see the maintaining projects). The string should be readable as a short prompt, expressing what the appropriate UID represents (like "Vendor UID" or "Interface UID");
- a combination of both the above, where the number is the former one and the string the latter, separated by a comma. If so, the number will be the UID's default value, but the UID will be editable (again the string should contain a short prompt). In this case, though, the UID value will not be stored in the UID database (see the UID management).
For example, for a bundle project type the array is defined this way:
XSdkUIDSetting = (268435577,"Interface ID","0,Vendor ID");
ensuring that the bundle (ie. polymorphic interface DLL)'s UID1 will be a fixed number 268435577, for the UID2 will be automatically allocated a free temporary UID (editable later as an "Interface ID", and the UID3 will be initialized to zero, but editable later as a "Vendor ID". The UID2 will be stored in the XSdk UID datbase, whilst the UID3 will not.
AssistantTemplates contents
The generic structure of the AssitantTemplates folder is quite straighforward: it contains one subfolder for each available template. Each subfolder therefore will have one item in the template type pop-up list in the panel frame (see above).
No other files or folders are allowed in the AssitantTemplate folder. In cas you do need to store something there, name the file or folder with a leading dot--it will be ignored.
Template contents
Each template subfolder of the AssitantTemplates folder can contain the following files and folders:
- Name.txt: a plain text file, containing the name to be shown in the template type pop-up list in the panel frame. If this file does not exist, a folder name will be used instead. Note: the items are ordered by the folder name alphabetical order; therefore, should you want them to be ordered non-alphabetically, you must use the Name.txt files (at least in some templates).
- Info.txt: another plain text file, containing the text to be shown in the info pane below the main view area;
- Assistant.nib: a NIB file, containing the template customization control. It is described below;
- OtherKeys.plist: a dictionary, containing other keys in the PB.project file and the way how they should be set by default. It is described below;
- All: a folder, containing templates for all the files, which should be added to a project regardless the programming language (like resources). Templates are described below;
- <lang>: for each language, an appropriately named folder, containing the templates for files, which should be added to a project in case the language was selected. Currently, the following language names are defined: CPP for C++, ObjC for Objective C, OPL, and Java for the appropriate langauges. The XSdk supports Fortran as well, but it is not (yet?) possible to create a whole project in it, thus it is not listed here.
Assistant.nib
The NIB must contain one view, bound to a File's Owner property named assistantView. Supposedly, the view will be something like NSBox (it is placed into a scroll view, so there is no need to implement scrolling there), containing all the customization controls. There can be any number of other controls; they are ignored (but will be properly shown).
Note: there will be soon a support for a bundle with code to be associated with the view.
Each customization control must have a name. It is assigned to it using its tooltip: when a tooltip has a contents "<x>#<y>", the <x> string becomes the true tooltip (it can be empty), and the <y> string is the customization control name.
The value for the name is determined automatically due to the class of the customization control:
| For a class... | ...is used a value |
|---|
| NSMatrix | the tag of the selected cell |
| NSPopUpButton | the tag of the selected menu item |
| NSButton | 1 in case the button's state differs from zero, 0 otherwise |
| NSTextField or NSTextView | the string contents of the object |
A dictionary of the combinations <name, value> is stored into the project using the key "XSdkAssistandDefaults". All the defaults set in all the superprojects are available for a subproject.
<<<more detailed description forthcoming>>>
File templates
<<<forthcoming: conditional !if/!else/!endif, using the customization names and values from the Assitant.nib>>>
OtherKeys.plist
<<<forthcoming>>>
If any of the three UIDs was not set by the OtherKeys, the default values from the Info.table are used automatically.
Copyright © 1999-2000 X.soft, all rights reserved