/usr/include/wxsmith/properties/wxspropertycontainer.h is in libwxsmithlib-dev 13.12+dfsg-4.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 | /*
* This file is part of wxSmith plugin for Code::Blocks Studio
* Copyright (C) 2006-2007 Bartlomiej Swiecki
*
* wxSmith is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 3 of the License, or
* (at your option) any later version.
*
* wxSmith is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with wxSmith. If not, see <http://www.gnu.org/licenses/>.
*
* $Revision: 8704 $
* $Id: wxspropertycontainer.h 8704 2012-12-23 20:32:03Z mortenmacfly $
* $HeadURL: http://svn.code.sf.net/p/codeblocks/code/branches/release-xx.yy/src/plugins/contrib/wxSmith/properties/wxspropertycontainer.h $
*/
#ifndef WXSPROPERTYCONTAINER_H
#define WXSPROPERTYCONTAINER_H
#include "wxsproperty.h"
#include "wxsquickpropspanel.h"
#include <prep.h>
class wxsPropertyGridManager;
/** \brief Base class for objects using properties
*
* This class is responsible for operating on properties.
* It also creates property window.
*/
class wxsPropertyContainer
{
public:
/** \brief Ctor */
wxsPropertyContainer();
/** \brief Dctor */
virtual ~wxsPropertyContainer();
/** \brief Changing Property Grid focus to this object
*
* This function can be used when this object is selected
* to make main property grid point to it.
*/
void ShowInPropertyGrid();
/** \brief Function reading all properties from Xml node
* \param Element Xml element containing all elements of properties
* as child nodes
*/
void XmlRead(TiXmlElement* Element);
/** \brief Function writing all properties to Xml node
* \param Element Xml element where all elements of properties
* will be added
*/
void XmlWrite(TiXmlElement* Element);
/** \brief Function reading all properties from property stream */
void PropStreamRead(wxsPropertyStream* Stream);
/** \brief Function writing all properties to property stream */
void PropStreamWrite(wxsPropertyStream* Stream);
/** \brief Function building new quick properties panel.
*
* If there was panel before, it will be unbinded from current object
* (and thus become useless) and new one will be binded.
*/
wxsQuickPropsPanel* BuildQuickPropertiesPanel(wxWindow* Parent);
/** \brief Function notifying about property change
*
* This function must be called when value of any property
* has been changed externally (not from property grid nor
* quick properties - there are special functions for them)
* It causes property grid and quick properties panel to
* reread it's content.
*
* \param CallPropertyChangeHandler - if true, PropertyChangeHandler will be called.
*/
void NotifyPropertyChange(bool CallPropertyChangeHandler=false);
/** \brief Operator reading from property stream */
inline wxsPropertyStream& operator>>(wxsPropertyStream& Stream)
{
PropStreamRead(&Stream);
return Stream;
}
/** \brief Operator writing to property stream */
inline wxsPropertyStream& operator<<(wxsPropertyStream& Stream)
{
PropStreamWrite(&Stream);
return Stream;
}
/** \brief Function returning flags of availability for this object
*
* These flags are passed to OnEnumProperties function and are used for
* filtering flags inside Property function.
* Using flags one can easily filter used properties.
*
* There are special reserved flags, which are put over properties
* returned here before using flags:
* \li flPropGrid - this flag is set when operating on property grid
* \li flXml - this flag is set when current operation is XmlRead or XmlWrite
* \li flPropStream - this flag is set when operating on property stream
* These flags are available only from OnEnumProperties or Property
* functions, there's no way to check them outside.
*/
inline long GetPropertiesFlags() { return OnGetPropertiesFlags(); }
protected:
/** \copydoc wxsPropertyContainer::GetPropertiesFlags() */
virtual long OnGetPropertiesFlags() { return -1; }
/** \brief Function enumerating properties
*
* This function MUST call Property or one of SubContainer functions
* for each property or sub container which will be used. Properties
* must be declared as static objects - static class members or static
* function variables (the second one is preferred since properties will
* be created when they are really needed).
*
* Example of registering function:
* \code
* void SomeClass::OnEnumProperties(long Flags)
* {
* static wxsLongProperty Prop1(_("Long value"),_T("value"),wxsOFFSET(SomeClass,VariableName));
* if ( Flags & flXrc )
* {
* Property(Prop1);
* }
* ... or equal to previous 3 lines ...
* Property(Prop1,flXrc);
* }
* \endcode
*/
virtual void OnEnumProperties(long Flags) = 0;
/** \brief Function registering property
*
* \note This function may be called only inside OnEnumProperties function
*
* \param Prop reference to property object which will be used
* \param Priority priority of this property, it's used while creating property grid
* to arrange properties.
*/
void Property(wxsProperty& Prop);
/** \brief Function enumerating properties of other container
* \note This function may be called only inside OnEnumProperties function
*/
inline void SubContainer(wxsPropertyContainer* Container)
{
if ( Container ) SubContainer(Container,Container->GetPropertiesFlags());
}
/** \brief Function enumerating properties of other container from it's reference
* \note This function may be called only inside OnEnumProperties function
*/
inline void SubContainer(wxsPropertyContainer& Container)
{
SubContainer(&Container);
}
/** \brief Function enumerating properties of other container overriding it's flags
* \note This function may be called only inside OnEnumProperties function
*/
void SubContainer(wxsPropertyContainer* Container,long NewFlags);
/** \brief Function enumerating properties of other container overriding it's flags
* \note This function may be called only inside OnEnumProperties function
*/
inline void SubContainer(wxsPropertyContainer& Container,long NewFlags)
{
SubContainer(&Container,NewFlags);
}
/** \brief Function building quick properties window */
virtual wxsQuickPropsPanel* OnCreateQuickProperties(cb_unused wxWindow* Parent) { return 0; }
/** \brief Function notifying that one of properties has changed
*
* This function may be redefined in derived classes to get notified
* about change of it's properties.
*/
virtual void OnPropertyChanged() {}
/** \brief Function notifying that one of properties in sub-containers has changed
*
* This function may be redefined in derived classes to get notified
* about change of sub-container property change.
* Sub-container is other container called in OnEnumProperties using
* SubContainer method.
*/
virtual void OnSubPropertyChanged(cb_unused wxsPropertyContainer* sc) {}
/** \brief Flag set when operating on property grid */
static const long flPropGrid = 0x40000000;
/** \brief Flag set when operating on xml */
static const long flXml = 0x20000000;
/** \brief Flag set when operating on property stream */
static const long flPropStream = 0x10000000;
/** \brief In this function derived classes may add extra tabs to property grid
*
* \warning This function is not called for sub-containers.
*/
virtual void OnAddExtraProperties(cb_unused wxsPropertyGridManager* Grid) {}
/** \brief Function notifying that some extra property (which could be added
* inside OnAddExtraProperties call) has changed.
*/
virtual void OnExtraPropertyChanged(cb_unused wxsPropertyGridManager* Grid,
cb_unused wxPGId Id) {}
private:
/** \brief Function notifying change of any property inside property grid */
void NotifyPropertyChangeFromPropertyGrid();
/** \brief Function notifying change of any property inside quick properties panel */
void NotifyPropertyChangeFromQuickProps();
wxsQuickPropsPanel* CurrentQP; /// \brief Currently associated quick properties panel
bool BlockChangeCallback; /// \brief set to true if should block NotifyChange functions -
/// it will be used to avoid recursive calling of property
/// change when updating editors
static long Flags; /// \brief Local cache of availability flags
static bool IsRead; /// \brief Used to determine whether we are reading or writing data
static TiXmlElement* CurrentElement; /// \brief Local cache of current xml node
static wxsPropertyStream* CurrentStream;/// \brief Local cache of current property stream
static wxMutex Mutex; /// \brief Mutex used when operating on properties
friend class wxsPropertyGridManager;
friend class wxsQuickPropsPanel;
friend class wxsProperty;
};
#endif
/**
\page wxSmith
\section wxsProperties Properties system
All items inside window resource (and maybe other items in future) are using
internal wxSmith's properties system. Properties are used for four basic
purposes:
\li Integrating with property grid (reading / writing / managing content)
\li Integrating with xml files using xrc structure (reading / writing)
\li Integrating with properties streams - streams were designed for wide
range of actions, mainly reading, writing and correcting data in
user-defined form
\li Integrating with quick properties system (this does not depend on
separate properties but uses whole container)
Each object using properties system has list of properties objects - classes
which manage data. Each property object is responsible for first three purposes
described above. Mainly property object takes one or more variables from
class and provides procedures operating on them. These procedures are unified
and thus operating on properties is identical in all cases, no matter what's
type of data.
\subsection wxsPropertyGridManager Property Grid Manager
There should be one instance of wxsPropertyGridManager widget somewhere in
system. This is singleton-like class which will be used as main property grid.
When this class is not provided, properties will work fine, but will be
generally useless.
\subsection wxsPropertyContainer Property containers
Objects using properties must be derived from wxsPropertyContainer class.
Basically this class provides array of properties objects (wxsProperty*
classes), and it provides all four groups of actions described at the beginning
of this page.
Deriving from wxsPropertyContainer class require defining GetProperties
method. This method is used to get list of properties associated with this
class. This function should return static array of wxsProperty* objects
(properties should be created once for class, not for instance of class)
wxsPropertyContainer additionally provides NotifyPropertyChange function
which is called whenever value of any property is changed. This function may
be used to refresh other components and to validate property values. When
value of property is changed inside NotifyPropertyChange, it will be refreshed
automatically after return.
Other functions provided in wxsPropertyContainer are:
\li \link wxsPropertyContainer::ShowInPropertyGrid ShowInPropertyGrid \endlink
this function is used to select item currently edited in main property
grid
\li \link wxsPropertyContainer::NotifyPropertyChange NotifyPropertyChange
\endlink this function should be called when any of properties is
changed outside. It is rereading data in property grid, quick properties
panel and may raise internal notification about property change.
\li \link wxsPropertyContainer::XmlRead XmlRead \endlink this function reads
values of all properties from given Xml node
\li \link wxsPropertyContainer::XmlWrite XmlWrite \endlink this function writes
values of all properties to given Xml node
\li \link wxsPropertyContainer::PropStreamRead PropStreamRead \endlink this
function reads values of all properties from given property stream
( \link wxsPropertyContainer::operator>> operator >> \endlink may be
used instead)
\li \link wxsPropertyContainer::PropStreamWrite PropStreamWrite \endlink this
function writes vaues of all properties to given
property stream ( \link wxsPropertyContainer::operator<< operator <<
\endlink may be used instead)
\li \link wxsPropertyContainer::BuildQuickPropertiesPanel
BuildQuickPropertiesPanel \endlink which creates and associates new
quick properties panel (described below)
\subsection wxsPropertyObject property object
Property object is object responsible for managing one or more variables in
class and for providing unified functions operating on it. These functions can
be divided to three groups (almost same as property container base tasks,
without support for quick properties):
\li Functions operating on property grid
- \link wxsProperty::PGCreate PGCreate \endlink function creating entry
in property grid and filling it with proper data
- \link wxsProperty::PGRead PGRead \endlink function reading values from
property grid and storing them in real variables
- \link wxsProperty::PGWrite PGWrite \endlink function updating value
of property in property grid (reading from real variables and storing
it inside property grid)
\li Functions operating on xml data
- \link wxsProperty::XmlRead XmlRead \endlink function reading value
from given xml node and storing it inside real variables (or resetting
values to default ones on read errors)
- \link wxsProperty::XmlWrite XmlWrite \endlink function writing value
to given xml node (read from real variable), also see note at the end
of this subsection
\li Functions operating on property streams
- \link wxsProperty::PropStreamRead PropStreamRead \endlink function
reading value from property stream and storing it inside real
variables
- \link wxsProperty::PropStreamWrite PropStreamWrite \endlink function
writing value of real variables to property stream
Adding new property require defining all those functions in new property
class. Additionally wxsCutomEditorProperty class may be used. This class
defines all PG... functions, but other are added:
\li \link wxsCustomEditorProperty::ShowEditor ShowEditor \endlink inside
this function, edit dialog should be created and showed in modal. Dialog
should be destroyed before exiting (in usual case). This function is
declared public to allow other items than property grid to show
property editor.
\li \link wxsCustomEditorProperty::GetStr GetStr \endlink this function
returns string built from property value. This function and
next ones are not required but may be added to increase property
functionality.
\li \link wxsCustomEditorProperty::ParseStr ParseStr \endlink this function
should parse given string and fetch property value from it. It's not
required.
\li \link wxsCustomEditorProperty::CanParseStr CanParseStr \endlink this
function notifies if this property is able to parse string (if ParseStr
function has been defined). If yes, user may edit property using
property editor or by writing string in property grid. This function
is not required.
\note Usually when saving data to Xml node, it should not be stored when
values are equal to default ones. If it's not done in such way, this
must be notified in class documentation.
\subsection wxsQuickPropsPanel Quick Properties Panel
Quick properties panel is additional editor area where properties can be
changed. It's purpose is to allow editing most useful properties in easier
way than in property grid and to make the edition more intuitive (very
standardized treatment in property grid does not leave much place to any kind
of invention).
Each property container may have one quick properties editor at one time.
Panel may be taken using wxsPropertyContainer::BuildQuickPropsPanel function.
To create panel inside class, OnCreateQuickProperties member function must be
re-declared and must return pointer to newly created quick properties panel.
Valid wxsPropertyContainer pointer must be passed to wxsQuickPropsPanel
constructor.
Note that Quick Properties Panel must be managed outside property container.
Container won't delete it. Only bindings are deleted.
\warning Do not use OnCreateQuickProperties function for getting panel since it
does not unbind previous quick properties panel and does not bind new one with
container correctly.
*/
|