From 09ad05faf01979b758764bf68746232ffa469ca8 Mon Sep 17 00:00:00 2001 From: Bryan Petty Date: Mon, 28 Apr 2008 08:26:04 +0000 Subject: [PATCH] Removed deprecated layout constraints from class summary, and more v* header reviews. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@53391 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/doxygen/Doxyfile_inc | 3 +- docs/doxygen/mainpages/cat_classes.h | 9 +- interface/variant.h | 358 +++++++++++++++------------ interface/vector.h | 27 +- interface/vidmode.h | 20 +- 5 files changed, 233 insertions(+), 184 deletions(-) diff --git a/docs/doxygen/Doxyfile_inc b/docs/doxygen/Doxyfile_inc index a493951ec2..3490400a39 100644 --- a/docs/doxygen/Doxyfile_inc +++ b/docs/doxygen/Doxyfile_inc @@ -200,6 +200,7 @@ ENABLED_SECTIONS = WXPERL_MANUAL WXPYTHON_MANUAL MAX_INITIALIZER_LINES = 30 SHOW_USED_FILES = YES SHOW_DIRECTORIES = YES +#SHOW_FILES = NO # Doxygen 1.5.6+ FILE_VERSION_FILTER = #--------------------------------------------------------------------------- @@ -314,7 +315,7 @@ GENERATE_XML = NO # Only change in format output configs XML_OUTPUT = xml XML_SCHEMA = XML_DTD = -XML_PROGRAMLISTING = YES +XML_PROGRAMLISTING = NO #--------------------------------------------------------------------------- # configuration options for the AutoGen Definitions output diff --git a/docs/doxygen/mainpages/cat_classes.h b/docs/doxygen/mainpages/cat_classes.h index f46a0a9c07..fae07d785c 100644 --- a/docs/doxygen/mainpages/cat_classes.h +++ b/docs/doxygen/mainpages/cat_classes.h @@ -86,7 +86,7 @@ thinking and calculating and will in almost all cases produce dialogs looking equally well on all platforms, the other is based on so-called constraints and is deprecated, though still available. -Related Overviews: @ref overview_sizer, @ref overview_constraints +Related Overviews: @ref overview_sizer These are the classes relevant to sizer-based layout: @@ -100,11 +100,6 @@ These are the classes relevant to sizer-based layout: @li wxStaticBoxSizer: Same as wxBoxSizer, but with a surrounding static box @li wxWrapSizer: A sizer which wraps its child controls as size permits -These are the classes relevant to constraints-based window layout: - -@li wxIndividualLayoutConstraint: Represents a single constraint dimension -@li wxLayoutConstraints: Represents the constraints for a window class - Other layout classes: @li wxLayoutAlgorithm: An alternative window layout facility @@ -484,7 +479,7 @@ Related Overviews: @ref overview_validator @li wxApp: Application class @li wxCmdLineParser: Command line parser class -@li wxDllLoader: Class to work with shared libraries. +@li wxDynamicLibrary: Class to work with shared libraries. @li wxProcess: Process class diff --git a/interface/variant.h b/interface/variant.h index 5a5dd47c79..e276cce933 100644 --- a/interface/variant.h +++ b/interface/variant.h @@ -10,36 +10,37 @@ @class wxVariant @wxheader{variant.h} - The @b wxVariant class represents a container for any type. A variant's value + The wxVariant class represents a container for any type. A variant's value can be changed at run time, possibly to a different type of value. As standard, wxVariant can store values of type bool, wxChar, double, long, - string, string list, time, date, void pointer, list of strings, and list of variants. - However, an application can extend wxVariant's capabilities by deriving from the - class wxVariantData and using the wxVariantData form of the wxVariant constructor - or assignment operator to assign this data to a variant. - Actual values for user-defined types will need to be accessed via the wxVariantData - object, unlike the case for basic data types where convenience functions such as - wxVariant::GetLong can be used. - - Pointers to any wxObject derived class can also easily be stored in a wxVariant. - wxVariant will then use wxWidgets' built-in RTTI system to set the type name - (returned by wxVariant::GetType) and to perform type-safety checks at runtime. - - This class is useful for reducing the programming for certain tasks, such as - an editor for different data types, or a remote procedure call protocol. + string, string list, time, date, void pointer, list of strings, and list of + variants. However, an application can extend wxVariant's capabilities by + deriving from the class wxVariantData and using the wxVariantData form of + the wxVariant constructor or assignment operator to assign this data to a + variant. Actual values for user-defined types will need to be accessed via + the wxVariantData object, unlike the case for basic data types where + convenience functions such as GetLong() can be used. + + Pointers to any wxObject derived class can also easily be stored in a + wxVariant. wxVariant will then use wxWidgets' built-in RTTI system to set + the type name (returned by GetType()) and to perform type-safety checks at + runtime. + + This class is useful for reducing the programming for certain tasks, such + as an editor for different data types, or a remote procedure call protocol. An optional name member is associated with a wxVariant. This might be used, - for example, in CORBA or OLE automation classes, where named parameters are required. + for example, in CORBA or OLE automation classes, where named parameters are + required. - Note that as of wxWidgets 2.7.1, wxVariant is @ref overview_trefcount - "reference counted". - Additionally, the convenience macros @b DECLARE_VARIANT_OBJECT and - @b IMPLEMENT_VARIANT_OBJECT were added so that adding (limited) support - for conversion to and from wxVariant can be very easily implemented - without modifying either wxVariant or the class to be stored by wxVariant. - Since assignment operators cannot be declared outside the class, the shift - left operators are used like this: + Note that as of wxWidgets 2.7.1, wxVariant is + @ref overview_refcount "reference counted". Additionally, the convenience + macros DECLARE_VARIANT_OBJECT() and IMPLEMENT_VARIANT_OBJECT() were added + so that adding (limited) support for conversion to and from wxVariant can + be very easily implemented without modifying either wxVariant or the class + to be stored by wxVariant. Since assignment operators cannot be declared + outside the class, the shift left operators are used like this: @code // in the header file @@ -57,14 +58,13 @@ value << variant; @endcode - For this to work, MyClass must derive from wxObject, implement - the @ref overview_runtimeclassoverview "wxWidgets RTTI system" - and support the assignment operator and equality operator for itself. Ideally, - it - should also be reference counted to make copying operations cheap and fast. This - can be most easily implemented using the reference counting support offered by - wxObject itself. By default, wxWidgets already implements - the shift operator conversion for a few of its drawing related classes: + For this to work, MyClass must derive from wxObject, implement the + @ref overview_rtti "wxWidgets RTTI system" and support the assignment + operator and equality operator for itself. Ideally, it should also be + reference counted to make copying operations cheap and fast. This can be + most easily implemented using the reference counting support offered by + wxObject itself. By default, wxWidgets already implements the shift + operator conversion for a few of its drawing related classes: @code IMPLEMENT_VARIANT_OBJECT(wxColour) @@ -73,16 +73,18 @@ IMPLEMENT_VARIANT_OBJECT(wxBitmap) @endcode - Note that as of wxWidgets 2.9.0, wxVariantData no longer inherits from wxObject - and wxVariant no longer uses the type-unsafe wxList class for list + Note that as of wxWidgets 2.9.0, wxVariantData no longer inherits from + wxObject and wxVariant no longer uses the type-unsafe wxList class for list operations but the type-safe wxVariantList class. Also, wxVariantData now - supports the Clone function for implementing the wxVariant::Unshare function. - Clone is implemented automatically by IMPLEMENT_VARIANT_OBJECT. + supports the wxVariantData::Clone() function for implementing the Unshare() + function. wxVariantData::Clone() is implemented automatically by + IMPLEMENT_VARIANT_OBJECT(). - Since wxVariantData no longer derives from wxObject, any code that tests the - type of the data using wxDynamicCast will require adjustment. You can use the - macro wxDynamicCastVariantData with the same arguments as wxDynamicCast, to - use C++ RTTI type information instead of wxWidgets RTTI. + Since wxVariantData no longer derives from wxObject, any code that tests + the type of the data using wxDynamicCast() will require adjustment. You can + use the macro wxDynamicCastVariantData() with the same arguments as + wxDynamicCast(), to use C++ RTTI type information instead of wxWidgets + RTTI. @library{wxbase} @category{data} @@ -98,15 +100,15 @@ public: wxVariant(); /** - Constructs a variant directly with a wxVariantData - object. wxVariant will take ownership of the wxVariantData - and will not increase its reference count. + Constructs a variant directly with a wxVariantData object. wxVariant + will take ownership of the wxVariantData and will not increase its + reference count. */ wxVariant(wxVariantData* data, const wxString& name = ""); /** - Constructs a variant from another variant by increasing the - reference count. + Constructs a variant from another variant by increasing the reference + count. */ wxVariant(const wxVariant& variant); @@ -143,8 +145,7 @@ public: /** Constructs a variant from a list of variants */ - wxVariant(const wxVariantList& value, - const wxString& name = ""); + wxVariant(const wxVariantList& value, const wxString& name = ""); /** Constructs a variant from a void pointer. @@ -169,73 +170,88 @@ public: /** Destructor. - Note that destructor is protected, so wxVariantData cannot usually - be deleted. Instead, wxVariantData::DecRef should be called. - See @ref overview_refcountdestruct "reference-counted object destruction" for - more info. + + @note wxVariantData's destructor is protected, so wxVariantData cannot + usually be deleted. Instead, wxVariantData::DecRef() should be + called. See @ref overview_refcount_destruct + "reference-counted object destruction" for more info. */ ~wxVariant(); + /** - @name List functionality + @name List Functionality */ //@{ + /** Returns the value at @a idx (zero-based). */ - wxVariant operator [](size_t idx); + wxVariant operator [](size_t idx) const; /** - Returns a reference to the value at @a idx (zero-based). This can be used - to change the value at this index. + Returns a reference to the value at @a idx (zero-based). This can be + used to change the value at this index. */ - const wxVariant& operator [](size_t idx); + wxVariant& operator [](size_t idx); + /** Appends a value to the list. */ void Append(const wxVariant& value); + + /** + Makes the variant null by deleting the internal data and set the name + to wxEmptyString. + */ + void Clear(); + /** Deletes the contents of the list. */ void ClearList(); + /** Deletes the zero-based @a item from the list. */ bool Delete(size_t item); + /** Returns the number of elements in the list. */ size_t GetCount() const; + /** - Returns a reference to the wxVariantList class used by - wxVariant if this wxVariant is currently a list of variants. + Returns a reference to the wxVariantList class used by wxVariant if + this wxVariant is currently a list of variants. */ wxVariantList& GetList() const; - /** - Makes the variant null by deleting the internal data and - set the name to @e wxEmptyString. - */ - void Clear(); + /** Inserts a value at the front of the list. */ void Insert(const wxVariant& value); + /** - Makes an empty list. This differs from a null variant which has no data; - a null list is of type list, but the number of elements in the list is zero. + Makes an empty list. This differs from a null variant which has no + data; a null list is of type list, but the number of elements in the + list is zero. */ void NullList(); + //@} + //@{ /** - Retrieves and converts the value of this variant to the type that @a value is. + Retrieves and converts the value of this variant to the type that + @a value is. */ bool Convert(long* value) const; - const bool Convert(bool* value) const; - const bool Convert(double* value) const; - const bool Convert(wxString* value) const; - const bool Convert(wxChar* value) const; - const bool Convert(wxDateTime* value) const; + bool Convert(bool* value) const; + bool Convert(double* value) const; + bool Convert(wxString* value) const; + bool Convert(wxChar* value) const; + bool Convert(wxDateTime* value) const; //@} /** @@ -254,10 +270,9 @@ public: wxChar GetChar() const; /** - Returns a pointer to the internal variant data. To take ownership - of this data, you must call its wxVariantData::IncRef - method. When you stop using it, wxVariantData::DecRef - must be likewise called. + Returns a pointer to the internal variant data. To take ownership of + this data, you must call its wxVariantData::IncRef() method. When you + stop using it, wxVariantData::DecRef() must be called as well. */ wxVariantData* GetData() const; @@ -287,10 +302,21 @@ public: wxString GetString() const; /** - Returns the value type as a string. The built-in types are: bool, char, - datetime, double, list, long, string, arrstring, void*. - If the variant is null, the value type returned is the string "null" (not the - empty string). + Returns the value type as a string. + + The built-in types are: + - "bool" + - "char" + - "datetime" + - "double" + - "list" + - "long" + - "string" + - "arrstring" + - "void*" + + If the variant is null, the value type returned is the string "null" + (not the empty string). */ wxString GetType() const; @@ -305,21 +331,22 @@ public: wxObject* GetWxObjectPtr() const; /** - Returns @true if there is no data associated with this variant, @false if there - is data. + Returns @true if there is no data associated with this variant, @false + if there is data. */ bool IsNull() const; /** - Returns @true if @a type matches the type of the variant, @false otherwise. + Returns @true if @a type matches the type of the variant, @false + otherwise. */ bool IsType(const wxString& type) const; /** - Returns @true if the data is derived from the class described by @e type, @false - otherwise. + Returns @true if the data is derived from the class described by + @a type, @false otherwise. */ - bool IsValueKindOf(const wxClassInfo* type type) const; + bool IsValueKindOf(const wxClassInfo* type) const; /** Makes the variant null by deleting the internal data. @@ -337,40 +364,41 @@ public: bool Member(const wxVariant& value) const; /** - Sets the internal variant data, deleting the existing data if there is any. + Sets the internal variant data, deleting the existing data if there is + any. */ void SetData(wxVariantData* data); /** - Makes sure that any data associated with this variant is not shared with other - variants. For this to work, wxVariantData::Clone must - be implemented for the data types you are working with. Clone is implemented - for all the default data types. + Makes sure that any data associated with this variant is not shared + with other variants. For this to work, wxVariantData::Clone() must be + implemented for the data types you are working with. + wxVariantData::Clone() is implemented for all the default data types. */ bool Unshare(); //@{ /** - Inequality test operators. + Inequality test operator. */ bool operator !=(const wxVariant& value) const; - const bool operator !=(const wxString& value) const; - const bool operator !=(const wxChar* value) const; - const bool operator !=(wxChar value) const; - const bool operator !=(const long value) const; - const bool operator !=(const bool value) const; - const bool operator !=(const double value) const; - const bool operator !=(void* value) const; - const bool operator !=(wxObject* value) const; - const bool operator !=(const wxVariantList& value) const; - const bool operator !=(const wxArrayString& value) const; - const bool operator !=(const wxDateTime& value) const; + bool operator !=(const wxString& value) const; + bool operator !=(const wxChar* value) const; + bool operator !=(wxChar value) const; + bool operator !=(const long value) const; + bool operator !=(const bool value) const; + bool operator !=(const double value) const; + bool operator !=(void* value) const; + bool operator !=(wxObject* value) const; + bool operator !=(const wxVariantList& value) const; + bool operator !=(const wxArrayString& value) const; + bool operator !=(const wxDateTime& value) const; //@} //@{ /** - Assignment operators, using @ref overview_trefcount "reference counting" when - possible. + Assignment operator, using @ref overview_refcount "reference counting" + if possible. */ void operator =(const wxVariant& value); void operator =(wxVariantData* value); @@ -385,27 +413,24 @@ public: void operator =(const wxVariantList& value); void operator =(const wxDateTime& value); void operator =(const wxArrayString& value); - void operator =(const DATE_STRUCT* value); - void operator =(const TIME_STRUCT* value); - void operator =(const TIMESTAMP_STRUCT* value); //@} //@{ /** - Equality test operators. + Equality test operator. */ bool operator ==(const wxVariant& value) const; - const bool operator ==(const wxString& value) const; - const bool operator ==(const wxChar* value) const; - const bool operator ==(wxChar value) const; - const bool operator ==(const long value) const; - const bool operator ==(const bool value) const; - const bool operator ==(const double value) const; - const bool operator ==(void* value) const; - const bool operator ==(wxObject* value) const; - const bool operator ==(const wxVariantList& value) const; - const bool operator ==(const wxArrayString& value) const; - const bool operator ==(const wxDateTime& value) const; + bool operator ==(const wxString& value) const; + bool operator ==(const wxChar* value) const; + bool operator ==(wxChar value) const; + bool operator ==(const long value) const; + bool operator ==(const bool value) const; + bool operator ==(const double value) const; + bool operator ==(void* value) const; + bool operator ==(wxObject* value) const; + bool operator ==(const wxVariantList& value) const; + bool operator ==(const wxArrayString& value) const; + bool operator ==(const wxDateTime& value) const; //@} //@{ @@ -413,11 +438,12 @@ public: Operator for implicit conversion to a long, using GetLong(). */ double operator double() const; - const long operator long() const; + long operator long() const; //@} /** - Operator for implicit conversion to a pointer to a void, using GetVoidPtr(). + Operator for implicit conversion to a pointer to a void, using + GetVoidPtr(). */ void* operator void*() const; @@ -444,28 +470,24 @@ public: @class wxVariantData @wxheader{variant.h} - The @b wxVariantData class is used to implement a new type for wxVariant. + The wxVariantData class is used to implement a new type for wxVariant. Derive from wxVariantData, and override the pure virtual functions. wxVariantData is @ref overview_refcount "reference counted", but you don't - normally have to care about this, - as wxVariant manages the count automatically. However, in case your application - needs to take - ownership of wxVariantData, be aware that the object is created with reference - count of 1, - and passing it to wxVariant will not increase this. In other words, - wxVariantData::IncRef - needs to be called only if you both take ownership of wxVariantData and pass it - to a wxVariant. - Also note that the destructor is protected, so you can never explicitly delete - a wxVariantData - instance. Instead, wxVariantData::DecRef will delete the object automatically - when the reference count reaches zero. + normally have to care about this, as wxVariant manages the count + automatically. However, in case your application needs to take ownership of + wxVariantData, be aware that the object is created with a reference count + of 1, and passing it to wxVariant will not increase this. In other words, + IncRef() needs to be called only if you both take ownership of + wxVariantData and pass it to a wxVariant. Also note that the destructor is + protected, so you can never explicitly delete a wxVariantData instance. + Instead, DecRef() will delete the object automatically when the reference + count reaches zero. @library{wxbase} - @category{FIXME} + @category{data} - @see wxVariant + @see wxVariant, wxGetVariantCast() */ class wxVariantData { @@ -476,22 +498,23 @@ public: wxVariantData(); /** - This function can be overridden to clone the data. - Implement Clone if you wish wxVariant::Unshare to work - for your data. This function is implemented for all built-in data types. + This function can be overridden to clone the data. You must implement + this function in order for wxVariant::Unshare() to work for your data. + This function is implemented for all built-in data types. */ wxVariantData* Clone() const; /** Decreases reference count. If the count reaches zero, the object is automatically deleted. - Note that destructor of wxVariantData is protected, so delete - cannot be used as normal. Instead, DecRef() should be called. + + @note The destructor of wxVariantData is protected, so delete cannot be + used as normal. Instead, DecRef() should be called. */ void DecRef(); /** - Returns @true if this object is equal to @e data. + Returns @true if this object is equal to @a data. */ bool Eq(wxVariantData& data) const; @@ -502,39 +525,54 @@ public: /** If the data is a wxObject returns a pointer to the objects wxClassInfo - structure, if - the data isn't a wxObject the method returns @NULL. + structure, if the data isn't a wxObject the method returns @NULL. */ wxClassInfo* GetValueClassInfo() const; /** - Increases reference count. Note that initially wxVariantData has reference - count of 1. + Increases reference count. Note that initially wxVariantData has + reference count of 1. */ void IncRef(); - //@{ /** - Reads the data from @a stream or @e string. + Reads the data from @a stream. */ bool Read(ostream& stream); + /** + Reads the data from @a string. + */ bool Read(wxString& string); - //@} - //@{ /** - Writes the data to @a stream or @e string. + Writes the data to @a stream. */ bool Write(ostream& stream) const; - const bool Write(wxString& string) const; - //@} - /** - This macro returns the data stored in @e variant cast to the type @e classname - * if - the data is of this type (the check is done during the run-time) or - @NULL otherwise. + Writes the data to @a string. */ - classname* wxGetVariantCast(); + bool Write(wxString& string) const; }; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_rtti */ +//@{ + +/** + This macro returns a pointer to the data stored in @a var (wxVariant) cast + to the type @a classname if the data is of this type (the check is done + during the run-time) or @NULL otherwise. + + @header{wx/variant.h} + + @see @ref overview_rtti, wxDynamicCast() +*/ +#define wxGetVariantCast(var, classname) + +//@} + diff --git a/interface/vector.h b/interface/vector.h index 5492dba9f6..65e39a4a1d 100644 --- a/interface/vector.h +++ b/interface/vector.h @@ -12,16 +12,16 @@ wxVector is a template class which implements most of the @c std::vector class and can be used like it. - If wxWidgets is compiled in STL mode, wxVector will just be a typedef to @c - std::vector. Just like for @c std::vector, objects stored in wxVector - need to be @e assignable but don't have to be @e default constructible. + If wxWidgets is compiled in STL mode, wxVector will just be a typedef to + @c std::vector. Just like for @c std::vector, objects stored in wxVector + need to be @e assignable but don't have to be @e "default constructible". Please refer to the STL documentation for further information. @nolibrary @category{containers} - @see @ref overview_container, wxList, wxArray + @see @ref overview_container, wxList, wxArray */ template class wxVector @@ -49,12 +49,12 @@ public: ~wxVector(); /** - Returns item at position @e idx. + Returns item at position @a idx. */ const value_type& at(size_type idx) const; /** - Returns item at position @e idx. + Returns item at position @a idx. */ value_type& at(size_type idx); @@ -115,8 +115,8 @@ public: /** Erase items in the range @a first to @a last (@a last is not erased). - @return Iterator pointing to the item immediately after the - erased range. + @return Iterator pointing to the item immediately after the erased + range. */ iterator erase(iterator first, iterator last); @@ -140,15 +140,15 @@ public: /** Assignment operator. */ - wxVectorT& operator operator=(const wxVector& vb); + wxVector& operator=(const wxVector& vb); /** - Returns item at position @e idx. + Returns item at position @a idx. */ const value_type& operator[](size_type idx) const; /** - Returns item at position @e idx. + Returns item at position @a idx. */ value_type& operator[](size_type idx); @@ -168,5 +168,10 @@ public: @see capacity() */ void reserve(size_type n); + + /** + Returns the size of the vector. + */ + size_type size() const; }; diff --git a/interface/vidmode.h b/interface/vidmode.h index 43215eb0fd..a96d3192c9 100644 --- a/interface/vidmode.h +++ b/interface/vidmode.h @@ -13,7 +13,7 @@ Determines the sizes and locations of displays connected to the system. @library{wxcore} - @category{FIXME} + @category{misc} @stdobjects ::wxDefaultVideoMode @@ -59,16 +59,25 @@ public: */ bool IsOk() const; - /// The screen width in pixels (e.g. 640), 0 means unspecified. + /** + The screen width in pixels (e.g. 640), 0 means unspecified. + */ int w; - /// The screen height in pixels (e.g. 480), 0 means unspecified. + /** + The screen height in pixels (e.g. 480), 0 means unspecified. + */ int h; - /// Bits per pixel (e.g. 32), 1 is monochrome and 0 means unspecified/known. + /** + Bits per pixel (e.g. 32), 1 is monochrome and 0 means + unspecified/known. + */ int bpp; - /// Refresh frequency in Hz, 0 means unspecified/unknown. + /** + Refresh frequency in Hz, 0 means unspecified/unknown. + */ int refresh; }; @@ -76,3 +85,4 @@ public: A global wxVideoMode instance used by wxDisplay. */ wxVideoMode wxDefaultVideoMode; + -- 2.45.2