|
|
| (18 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| − | '''Warning - this tutorial requires some wxSmith code updates and not everything may work now'''
| |
| | | | |
| − |
| |
| − | == Preface ==
| |
| − |
| |
| − |
| |
| − | In [[Creating a plugin which adds new item into wxSmith|previous]] tutorial we created simple plugin which added one item into wxSmith's palette. After loading this plugin into Code::Blocks we were able to add this item into resource and set some basic properties like size or position. In this tutorial we will add more customization for this item by adding it's specific properties. But before we do this, I need to explain some things.
| |
| − |
| |
| − |
| |
| − | == How wxSmith creates properties ==
| |
| − |
| |
| − |
| |
| − | The final set of properties is result of merging three basic sets:
| |
| − | * Some standard properties which are used in almost any widget (size, position, font etc)
| |
| − | * Properties added by parent control like border size inside sizers or notebook page na
| |
| − | * Properties which are specific to one widget only
| |
| − |
| |
| − |
| |
| − | === Standard properties ===
| |
| − |
| |
| − |
| |
| − | The first set is added through constructor. In the code from previous tutorial, it's done like this:
| |
| − |
| |
| − | wxsChart::wxsChart(wxsItemResData* Data):
| |
| − | wxsWidget(
| |
| − | Data, // Data passed to constructor
| |
| − | &Reg.Info, // Info taken from Registering object previously created
| |
| − | NULL, // Structure describing events, we have no events for wxChart
| |
| − | wxsChartStyles) // Structure describing styles
| |
| − | {
| |
| − | }
| |
| − |
| |
| − | so the only thing we see here is set of styles (that's one of standard properties). Because it's rather complex and require extra initialization, this property must be specified separately. If there was <tt>NULL</tt> instead of <tt>wxsChartStyles</tt>, wxChart would have no style property.
| |
| − | Other standard properties are given through flags, which are passed through <tt>PropertiesFlags</tt> argument in constructor of wxsWidget:
| |
| − |
| |
| − | wxsWidget(
| |
| − | wxsItemResData* Data,
| |
| − | const wxsItemInfo* Info,
| |
| − | const wxsEventDesc* EventArray = NULL,
| |
| − | const wxsStyleSet* StyleSet=NULL,
| |
| − | long PropertiesFlags = flWidget);
| |
| − |
| |
| − | We can see here that default value for this argument is flWidget. It means that standard properties which are usually used by any kind of widget will be added into properties set. That value is silently passed to wxsWidget's constructor in case of wxsChart class so we have all those standard properties in property browser without even line of code. Individual flags which can be used are:
| |
| − |
| |
| − | * <tt>flVariable</tt> - allow variable and ''Is Member'' flag
| |
| − | * <tt>flId</tt> - allow identifier
| |
| − | * <tt>flPosition</tt> - allow position
| |
| − | * <tt>flSize</tt> - allow size
| |
| − | * <tt>flEnabled</tt> - allow ''Enabled'' switch
| |
| − | * <tt>flFocused</tt> - allow ''Focused'' switch
| |
| − | * <tt>flHidden</tt> - allow ''Hidden'' switch
| |
| − | * <tt>flColours</tt> - allow foreground and background colours
| |
| − | * <tt>flToolTip</tt> - allow tooltip
| |
| − | * <tt>flFont</tt> - allow font
| |
| − | * <tt>flHelpText</tt> - allow help text
| |
| − | * <tt>flSubclass</tt> - allow changing of class name (the ''"subclass"'' term comes from XRC terminology)
| |
| − | * <tt>flMinMaxSize</tt> - allow MinSize and MaxSize
| |
| − |
| |
| − | Some properties are also filtered depending on some circumstances:
| |
| − | * <tt>flMinMaxSize</tt> will be disabled when XRC file is used
| |
| − | * <tt>flVariable</tt> / <tt>flId</tt> are disabled for top-most items (like wxDialog and wxFrame)
| |
| − | * <tt>flHidden</tt> does not affect item when it's shown inside editor (but it's used for exact previews shown after pressing ''Preview'' button)
| |
| − |
| |
| − |
| |
| − | === Properties added by parent control ===
| |
| − |
| |
| − |
| |
| − | Some parent controls require extra information for each of it's children. This data is included in set of properties in property browser and child item have no control of it. Properties added in this way are:
| |
| − | * Settings for item inside sizer (''border size'', ''border flags'', ''proportion'' and some flags like ''expand')
| |
| − | * Names of pages and switch for default page in wxNotebook, wxChoicebook and wxListbook
| |
| − |
| |
| − |
| |
| − | === Properties specific to only one item ===
| |
| − |
| |
| − |
| |
| − | Most of items have their own proeprties which can not be generalized and provided as common ones. These properties are added in special function which in case of widgets is declared as:
| |
| − |
| |
| − | void OnEnumWidgetProperties(long Flags);
| |
| − |
| |
| − | wxSmith has complex property managment system which handle most of work related to propertiesautomatically, including operating on property grid and XRC files. Usually one variable is mapped to one property (in case of most complex properties such as position, special structure is used to keep data in one variable).
| |
| − | Binding between variable and property managment system is done in function mentioned above. It require generating one variable for one property and calling <tt>Property</tt> function for this variable. Usually ot looks like this:
| |
| − |
| |
| − | void ClassName::OnEnumWidgetProperties(long Flags)
| |
| − | {
| |
| − | static wxsBoolProperty SomePropertyVariable(
| |
| − | _("Name in property grid"), _T("name_in_xrc_file"),
| |
| − | wxsOFFSET(ClassName,ClassMemberVariable), false );
| |
| − | Property(SomePropertyValue);
| |
| − | }
| |
| − |
| |
| − | Properties may be added in this way or may be defined through macros. Using macro, the code adding bool property will look like this:
| |
| − |
| |
| − | void ClassName::OnEnumWidgetProperties(long Flags)
| |
| − | {
| |
| − | WXS_BOOL(ClassName,ClassMemberVariable,_("Name in property grid"), _T("name_in_xrc_file"), false);
| |
| − | }
| |
| − |
| |
| − | Both methods will give the same result (macros simply generate static variable and call Property on it). So it's up to you to choose one of them. I preffer macros because they give cleaner view, but smoetimes they may hide some extra parameters and may not be preffered by other coders (not everyone likes c macros ;) ). So I'll describe both methods.
| |
| − |
| |
| − | Before we begin detailed description of available properties, I'll have to make few remarks:
| |
| − | * Variables used in properties must be members of the class. It's possible to use members of other class, but it's advanced stuff and won't be covered in this tutorial. And it's not possible to create property from pointer to variable (for example when we have <tt>bool*</tt> member in class and want to make property for value pointer by it). The technique which allow such things will be described later in this tutorial but won't use wxSmith's property managment system.
| |
| − | * Objects which create binging between property variable and property managment system (like <tt>SomePropertyVariable</tt> in example above) should be declared static or at least should exist as long as all objects using this property are not deleted. Simple <tt>static</tt> modifier eliminates all problems.
| |
| − |
| |
| − |
| |
| − | ==== Properties list ====
| |
| − |
| |
| − | ===== bool =====
| |
| − |
| |
| − | Variable type: <tt>bool</tt>
| |
| − |
| |
| − | Exaple using macros:
| |
| − |
| |
| − | WXS_BOOL(
| |
| − | ClassName, // Name of this class
| |
| − | ClassMemberVariable, // Name of member variable
| |
| − | _("Name in property grid"), // Name of property shown in property grid
| |
| − | _T("name_in_xrc_file"), // Name of XML node used in xrc files
| |
| − | false); // Default value
| |
| − |
| |
| − | Example using objects:
| |
| − |
| |
| − | static wxsBoolProperty SomePropertyVariable(
| |
| − | _("Name in property grid"), // Name of property shown in property grid
| |
| − | _T("name_in_xrc_file"), // Name of XML node used in xrc files
| |
| − | wxsOFFSET(ClassName,ClassMemberVariable), // Offset from class beginning to variable
| |
| − | false ); // Default value
| |
| − | Property(SomePropertyValue);
| |
| − |
| |
| − |
| |
| − | ===== wxString =====
| |
| − |
| |
| − | Variable type: <tt>wxString</tt>
| |
| − |
| |
| − | Exaple using macros (for one-line strings):
| |
| − |
| |
| − | WXS_SHORT_STRING(
| |
| − | ClassName, // Name of this class
| |
| − | ClassMemberVariable, // Name of member variable
| |
| − | _("Name in property grid"), // Name of property shown in property grid
| |
| − | _T("name_in_xrc_file"), // Name of XML node used in xrc files
| |
| − | false, // Default value
| |
| − | false); // If set to true, empty strings won't be stored in XRC files (
| |
| − |
| |
| − | Exaple using macros (for multiline strings):
| |
| − |
| |
| − | WXS_STRING(
| |
| − | ClassName, // Name of this class
| |
| − | ClassMemberVariable, // Name of member variable
| |
| − | _("Name in property grid"), // Name of property shown in property grid
| |
| − | _T("name_in_xrc_file"), // Name of XML node used in xrc files
| |
| − | _T(""), // Default value
| |
| − | false); // If set to true, empty strings won't be stored in XRC files
| |
| − |
| |
| − | Example using objects:
| |
| − |
| |
| − | static wxsStringProperty SomePropertyVariable(
| |
| − | _("Name in property grid"), // Name of property shown in property grid
| |
| − | _T("name_in_xrc_file"), // Name of XML node used in xrc files
| |
| − | wxsOFFSET(ClassName,ClassMemberVariable), // Offset from class beginning to variable
| |
| − | true, // True for multiline string, false for one-line
| |
| − | _T("") ); // Default value
| |
| − | Property(SomePropertyValue);
| |
| − |
| |
| − | ===== long int =====
| |
| − |
| |
| − | Variable type: <tt>long int</tt>
| |
| − |
| |
| − | Exaple using macros:
| |
| − |
| |
| − | WXS_LONG(
| |
| − | ClassName, // Name of this class
| |
| − | ClassMemberVariable, // Name of member variable
| |
| − | _("Name in property grid"), // Name of property shown in property grid
| |
| − | _T("name_in_xrc_file"), // Name of XML node used in xrc files
| |
| − | 10); // Default value
| |
| − |
| |
| − | Example using objects:
| |
| − |
| |
| − | static wxsLongProperty SomePropertyVariable(
| |
| − | _("Name in property grid"), // Name of property shown in property grid
| |
| − | _T("name_in_xrc_file"), // Name of XML node used in xrc files
| |
| − | wxsOFFSET(ClassName,ClassMemberVariable), // Offset from class beginning to variable
| |
| − | 10); // Default value
| |
| − | Property(SomePropertyValue);
| |
| − |
| |
| − | ===== enum =====
| |
| − |
| |
| − | Variable type: <tt>long int</tt> which is one of predefined values
| |
| − |
| |
| − | Exaple using macros:
| |
| − |
| |
| − | static const long Values[] = { 5, 100 };
| |
| − | static const wxChar* Names[] = { _("Few"), _("Many"), NULL }; // Must end with NULL entry
| |
| − |
| |
| − | WXS_ENUM(
| |
| − | ClassName, // Name of this class
| |
| − | ClassMemberVariable, // Name of member variable
| |
| − | _("Name in property grid"), // Name of property shown in property grid
| |
| − | _T("name_in_xrc_file"), // Name of XML node used in xrc files
| |
| − | Values, // Array of values
| |
| − | Names, // Array of names
| |
| − | 5); // Default value
| |
| − |
| |
| − | Example using objects:
| |
| − |
| |
| − | static const long Values[] = { 5, 100 };
| |
| − | static const wxChar* Names[] = { _("Few"), _("Many"), NULL }; // Must end with NULL entry
| |
| − |
| |
| − | static wxsEnumProperty SomePropertyVariable(
| |
| − | _("Name in property grid"), // Name of property shown in property grid
| |
| − | _T("name_in_xrc_file"), // Name of XML node used in xrc files
| |
| − | wxsOFFSET(ClassName,ClassMemberVariable), // Offset from class beginning to variable
| |
| − | Values, // Array of values
| |
| − | Names, // Array of names
| |
| − | false, // Setting to true notifies that content of arrays may change (not tested)
| |
| − | 5, // Default value
| |
| − | true); // If false, XRC node will contain value as number, of true, it will contain name
| |
| − | Property(SomePropertyValue);
| |
| − |
| |
| − | ===== flags =====
| |
| − |
| |
| − | Variable type: <tt>long int</tt> which is value produced by or-ing some one-bit flags
| |
| − |
| |
| − | Exaple using macros:
| |
| − |
| |
| − | static const long Values[] = { 0x01, 0x02, 0x04, 0x08, 0x10 };
| |
| − | static const wxChar* Names[] = { _T("C"), _T("C++"), _T("Java"), _T("C#"), _T("D"), NULL };
| |
| − |
| |
| − | WXS_FLAGS(
| |
| − | ClassName, // Name of this class
| |
| − | ClassMemberVariable, // Name of member variable
| |
| − | _("Name in property grid"), // Name of property shown in property grid
| |
| − | _T("name_in_xrc_file"), // Name of XML node used in xrc files
| |
| − | Values, // Array of values
| |
| − | Names, // Array of names
| |
| − | 0x01 | 0x10 ); // Default value
| |
| − |
| |
| − | Example using objects:
| |
| − |
| |
| − | static const long Values[] = { 0x01, 0x02, 0x04, 0x08, 0x10 };
| |
| − | static const wxChar* Names[] = { _T("C"), _T("C++"), _T("Java"), _T("C#"), _T("D"), NULL };
| |
| − |
| |
| − | static wxsFlagsProperty SomePropertyVariable(
| |
| − | _("Name in property grid"), // Name of property shown in property grid
| |
| − | _T("name_in_xrc_file"), // Name of XML node used in xrc files
| |
| − | wxsOFFSET(ClassName,ClassMemberVariable), // Offset from class beginning to variable
| |
| − | Values, // Array of values
| |
| − | Names, // Array of names
| |
| − | false, // Setting to true notifies that content of arrays may change (not tested)
| |
| − | 0x01 | 0x10); // Default value
| |
| − | Property(SomePropertyValue);
| |
| − |
| |
| − | ===== wxArrayString =====
| |
| − |
| |
| − | ===== wxArrayString with checked items =====
| |
| − |
| |
| − | ===== wxBitmap =====
| |
| − |
| |
| − | ===== wxIcon =====
| |
| − |
| |
| − | ===== wxColour =====
| |
| − |
| |
| − | ===== wxDimension =====
| |
| − |
| |
| − | ===== wxFont =====
| |
| − |
| |
| − | ===== wxPosition =====
| |
| − |
| |
| − | ===== wxSize =====
| |
