Add wxPopupWindow

[wxWidgets.git] / interface / artprov.h

diff --git a/interface/artprov.h b/interface/artprov.h
index d46f0d8ae7dbf9f7cded2cc4667534cf3a3ea7a3..e6e13df2656fc448c0cd58f5270abff3c35c593a 100644 (file)
--- a/interface/artprov.h
+++ b/interface/artprov.h
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        artprov.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        artprov.h

-// Purpose:     documentation for wxArtProvider class
+// Purpose:     interface of wxArtProvider

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license


@@ -9,26 +9,26 @@
 /**
     @class wxArtProvider
     @wxheader{artprov.h}
 /**
     @class wxArtProvider
     @wxheader{artprov.h}

-    
+

     wxArtProvider class is used to customize the look of wxWidgets application.
     wxArtProvider class is used to customize the look of wxWidgets application.

+

     When wxWidgets needs to display an icon or a bitmap (e.g. in the standard file
     dialog), it does not use a hard-coded resource but asks wxArtProvider for it
     instead. This way users can plug in their own wxArtProvider class and easily
     When wxWidgets needs to display an icon or a bitmap (e.g. in the standard file
     dialog), it does not use a hard-coded resource but asks wxArtProvider for it
     instead. This way users can plug in their own wxArtProvider class and easily

-    replace standard art with their own version. All
-    that is needed is to derive a class from wxArtProvider, override either its
-    wxArtProvider::CreateBitmap and/or its
-    wxArtProvider::CreateIconBundle methods
-    and register the provider with
-    wxArtProvider::Push:
-    
+    replace standard art with their own version.
+
+    All that is needed is to derive a class from wxArtProvider, override either its
+    wxArtProvider::CreateBitmap() and/or its wxArtProvider::CreateIconBundle() methods
+    and register the provider with wxArtProvider::Push():
+

     @code
     @code

-    class MyProvider : public wxArtProvider
+      class MyProvider : public wxArtProvider

       {
       protected:
       {
       protected:

-        wxBitmap CreateBitmap(const wxArtID& id, 
+        wxBitmap CreateBitmap(const wxArtID& id,

                               const wxArtClient& client,
                               const wxSize size)
                               const wxArtClient& client,
                               const wxSize size)

-    
+

         // optionally override this one as well
         wxIconBundle CreateIconBundle(const wxArtID& id,
                                       const wxArtClient& client)
         // optionally override this one as well
         wxIconBundle CreateIconBundle(const wxArtID& id,
                                       const wxArtClient& client)


@@ -37,99 +37,122 @@
       ...
       wxArtProvider::Push(new MyProvider);
     @endcode
       ...
       wxArtProvider::Push(new MyProvider);
     @endcode

-    
+

     If you need bitmap images (of the same artwork) that should be displayed at
     If you need bitmap images (of the same artwork) that should be displayed at

-    different sizes
-    you should probably consider overriding wxArtProvider::CreateIconBundle 
+    different sizes you should probably consider overriding wxArtProvider::CreateIconBundle

     and supplying icon bundles that contain different bitmap sizes.
     and supplying icon bundles that contain different bitmap sizes.

-    
+

     There's another way of taking advantage of this class: you can use it in your
     There's another way of taking advantage of this class: you can use it in your

-    code and use
-    platform native icons as provided by wxArtProvider::GetBitmap or 
-    wxArtProvider::GetIcon (NB: this is not yet really
-    possible as of wxWidgets 2.3.3, the set of wxArtProvider bitmaps is too
-    small). 
-    
-    
-    wxArtProvider::~wxArtProvider
-    wxArtProvider::CreateBitmap
-    wxArtProvider::CreateIconBundle
-    wxArtProvider::Delete
-    wxArtProvider::GetBitmap
-    wxArtProvider::GetIconBundle
-    wxArtProvider::GetIcon
-    wxArtProvider::Insert
-    wxArtProvider::Pop
-    wxArtProvider::Push
-    wxArtProvider::Remove
-    
-    
-    Identifying art resources
-    
+    code and use platform native icons as provided by wxArtProvider::GetBitmap or
+    wxArtProvider::GetIcon.
+
+    @todo IS THIS NB TRUE?
+    (@note this is not yet really possible as of wxWidgets 2.3.3, the set of wxArtProvider
+     bitmaps is too small).
+
+    @section wxartprovider_identify Identifying art resources
+

     Every bitmap and icon bundle are known to wxArtProvider under an unique ID that
     Every bitmap and icon bundle are known to wxArtProvider under an unique ID that

-    is used when
-    requesting a resource from it. The ID is represented by wxArtID type and can
-    have one of these predefined values (you can see bitmaps represented by these
-    constants in the artprov sample):
-    
-     wxART_ERROR
-     wxART_QUESTION
-     wxART_WARNING
-     wxART_INFORMATION
-     wxART_ADD_BOOKMARK
-     wxART_DEL_BOOKMARK
-     wxART_HELP_SIDE_PANEL
-     wxART_HELP_SETTINGS
-     wxART_HELP_BOOK
-     wxART_HELP_FOLDER
-     wxART_HELP_PAGE
-     wxART_GO_BACK
-     wxART_GO_FORWARD
-     wxART_GO_UP
-     wxART_GO_DOWN
-     wxART_GO_TO_PARENT
-     wxART_GO_HOME
-     wxART_PRINT
-     wxART_HELP
-     wxART_TIP
-     wxART_REPORT_VIEW
-     wxART_LIST_VIEW
-     wxART_NEW_DIR
-     wxART_FOLDER
-     wxART_FOLDER_OPEN
-     wxART_GO_DIR_UP
-     wxART_EXECUTABLE_FILE
-     wxART_NORMAL_FILE
-     wxART_TICK_MARK
-     wxART_CROSS_MARK
-     wxART_MISSING_IMAGE
-     wxART_NEW
-     wxART_FILE_OPEN
-     wxART_FILE_SAVE
-     wxART_FILE_SAVE_AS
-     wxART_DELETE
-     wxART_COPY
-     wxART_CUT
-     wxART_PASTE
-     wxART_UNDO
-     wxART_REDO
-     wxART_QUIT
-     wxART_FIND
-     wxART_FIND_AND_REPLACE
-     wxART_HARDDISK
-     wxART_FLOPPY
-     wxART_CDROM
-     wxART_REMOVABLE
-    
-    
-    Additionally, any string recognized by custom art providers registered using 
+    is used when requesting a resource from it. The ID is represented by wxArtID type
+    and can have one of these predefined values (you can see bitmaps represented by these
+    constants in the @ref page_samples_artprovider):
+
+    <table>
+    <tr><td>
+     @li wxART_ERROR
+     @li wxART_QUESTION
+     @li wxART_WARNING
+     @li wxART_INFORMATION
+     @li wxART_ADD_BOOKMARK
+     @li wxART_DEL_BOOKMARK
+     @li wxART_HELP_SIDE_PANEL
+     @li wxART_HELP_SETTINGS
+     @li wxART_HELP_BOOK
+     @li wxART_HELP_FOLDER
+     @li wxART_HELP_PAGE
+     @li wxART_GO_BACK
+     @li wxART_GO_FORWARD
+     @li wxART_GO_UP
+    </td><td>
+     @li wxART_GO_DOWN
+     @li wxART_GO_TO_PARENT
+     @li wxART_GO_HOME
+     @li wxART_PRINT
+     @li wxART_HELP
+     @li wxART_TIP
+     @li wxART_REPORT_VIEW
+     @li wxART_LIST_VIEW
+     @li wxART_NEW_DIR
+     @li wxART_FOLDER
+     @li wxART_FOLDER_OPEN
+     @li wxART_GO_DIR_UP
+     @li wxART_EXECUTABLE_FILE
+     @li wxART_NORMAL_FILE
+     @li wxART_TICK_MARK
+     @li wxART_CROSS_MARK
+    </td><td>
+     @li wxART_MISSING_IMAGE
+     @li wxART_NEW
+     @li wxART_FILE_OPEN
+     @li wxART_FILE_SAVE
+     @li wxART_FILE_SAVE_AS
+     @li wxART_DELETE
+     @li wxART_COPY
+     @li wxART_CUT
+     @li wxART_PASTE
+     @li wxART_UNDO
+     @li wxART_REDO
+     @li wxART_QUIT
+     @li wxART_FIND
+     @li wxART_FIND_AND_REPLACE
+     @li wxART_HARDDISK
+     @li wxART_FLOPPY
+     @li wxART_CDROM
+     @li wxART_REMOVABLE
+    </td></tr>
+    </table>
+
+    Additionally, any string recognized by custom art providers registered using

     wxArtProvider::Push may be used.
     wxArtProvider::Push may be used.

-    
+
+    @note
+    When running under GTK+ 2, GTK+ stock item IDs (e.g. @c "gtk-cdrom") may be used
+    as well. Additionally, if wxGTK was compiled against GTK+ >= 2.4, then it is also
+    possible to load icons from current icon theme by specifying their name (without
+    extension and directory components).
+    Icon themes recognized by GTK+ follow the freedesktop.org Icon Themes specification
+    (see http://freedesktop.org/Standards/icon-theme-spec).
+    Note that themes are not guaranteed to contain all icons, so wxArtProvider may
+    return ::wxNullBitmap or ::wxNullIcon.
+    The default theme is typically installed in @c /usr/share/icons/hicolor.
+
+
+    @section wxartprovider_clients Clients
+
+    Client is the entity that calls wxArtProvider's GetBitmap or GetIcon function.
+    It is represented by wxClientID type and can have one of these values:
+
+    @li wxART_TOOLBAR
+    @li wxART_MENU
+    @li wxART_BUTTON
+    @li wxART_FRAME_ICON
+    @li wxART_CMN_DIALOG
+    @li wxART_HELP_BROWSER
+    @li wxART_MESSAGE_BOX
+    @li wxART_OTHER (used for all requests that don't fit into any of the
+        categories above)
+
+    Client ID servers as a hint to wxArtProvider that is supposed to help it to
+    choose the best looking bitmap. For example it is often desirable to use
+    slightly different icons in menus and toolbars even though they represent
+    the same action (e.g. wxART_FILE_OPEN). Remember that this is really only a
+    hint for wxArtProvider -- it is common that wxArtProvider::GetBitmap returns
+    identical bitmap for different client values!
+

     @library{wxcore}
     @library{wxcore}

-    @category{FIXME}
-    
-    @seealso
-    See the artprov sample for an example of wxArtProvider usage.
+    @category{misc,data}
+
+    @see the @ref page_samples_artprovider for an example of wxArtProvider usage.

 */
 class wxArtProvider : public wxObject
 {
 */
 class wxArtProvider : public wxObject
 {


@@ -138,205 +161,123 @@ public:
         The destructor automatically removes the provider from the provider stack used
         by GetBitmap().
     */
         The destructor automatically removes the provider from the provider stack used
         by GetBitmap().
     */

-    ~wxArtProvider();
-
-    /**
-        Client is the entity that calls wxArtProvider's GetBitmap or GetIcon
-        function. It is represented by wxClientID type and can have one of these 
-        values:
-        
-         wxART_TOOLBAR
-         wxART_MENU
-         wxART_BUTTON
-         wxART_FRAME_ICON
-         wxART_CMN_DIALOG
-         wxART_HELP_BROWSER
-         wxART_MESSAGE_BOX
-         wxART_OTHER (used for all requests that don't fit into any of the categories
-        above)
-        
-        Client ID servers as a hint to wxArtProvider that is supposed to help it to
-        choose the best looking bitmap. For example it is often desirable to use
-        slightly different icons in menus and toolbars even though they represent the
-        same action (e.g. @c wx_ART_FILE_OPEN). Remember that this is really
-        only a hint for wxArtProvider -- it is common that
-        GetBitmap() 
-        returns identical bitmap for different @e client values!
-        
-        @sa See the artprov sample for an example of wxArtProvider usage.
-    */
-
-
-    /**
-        Derived art provider classes must override this method to create requested art
-        resource. Note that returned bitmaps are cached by wxArtProvider and it is
-        therefore not necessary to optimize CreateBitmap() for speed (e.g. you may
-        create wxBitmap objects from XPMs here).
-        
-        @param id 
-        wxArtID unique identifier of the bitmap.
-        
-        @param client 
-        wxArtClient identifier of the client (i.e. who is asking for the bitmap).
-        This only servers as a hint.
-        
-        @param size 
-        Preferred size of the bitmap. The function may return a bitmap of different
-        dimensions, it will be automatically rescaled to meet client's request.
-        
-        @sa CreateIconBundle()
-    */
-    wxBitmap CreateBitmap(const wxArtID& id,
-                          const wxArtClient& client,
-                          const wxSize& size);
-
-    /**
-        This method is similar to CreateBitmap() but
-        can be used when a bitmap (or an icon) exists in several sizes.
-    */
-    wxIconBundle CreateIconBundle(const wxArtID& id,
-                                  const wxArtClient& client);
+    virtual ~wxArtProvider();

 
     /**
 
     /**

-        Delete the given @e provider.
+        Delete the given @a provider.

     */
     static bool Delete(wxArtProvider* provider);
 
     /**
         Query registered providers for bitmap with given ID.
     */
     static bool Delete(wxArtProvider* provider);
 
     /**
         Query registered providers for bitmap with given ID.

-        
-        @param id 
-        wxArtID unique identifier of the bitmap.
-        
-        @param client 
-        wxArtClient identifier of the client (i.e. who is asking for the bitmap).
-        
-        @param size 
-        Size of the returned bitmap or wxDefaultSize if size doesn't matter.
-        
+
+        @param id
+            wxArtID unique identifier of the bitmap.
+        @param client
+            wxArtClient identifier of the client (i.e. who is asking for the bitmap).
+        @param size
+            Size of the returned bitmap or wxDefaultSize if size doesn't matter.
+

         @returns The bitmap if one of registered providers recognizes the ID or
         @returns The bitmap if one of registered providers recognizes the ID or

-                   wxNullBitmap otherwise.
+                 wxNullBitmap otherwise.

     */
     static wxBitmap GetBitmap(const wxArtID& id,
                               const wxArtClient& client = wxART_OTHER,
                               const wxSize& size = wxDefaultSize);
 
     */
     static wxBitmap GetBitmap(const wxArtID& id,
                               const wxArtClient& client = wxART_OTHER,
                               const wxSize& size = wxDefaultSize);
 

-    //@{

     /**
     /**

-        Returns a suitable size hint for the given @e wxArtClient. If 
-        @e platform_default is @true, return a size based on the current platform, 
-        otherwise return the size from the topmost wxArtProvider. @e wxDefaultSize may
-        be 
-        returned if the client doesn't have a specified size, like wxART_OTHER for
-        example.
+        Same as wxArtProvider::GetBitmap, but return a wxIcon object
+        (or ::wxNullIcon on failure).

     */
     static wxIcon GetIcon(const wxArtID& id,
                           const wxArtClient& client = wxART_OTHER,
                           const wxSize& size = wxDefaultSize);
     */
     static wxIcon GetIcon(const wxArtID& id,
                           const wxArtClient& client = wxART_OTHER,
                           const wxSize& size = wxDefaultSize);

-        static wxSize GetSizeHint(const wxArtClient& client,
-                                  bool platform_default = @false);
-    //@}
+
+    /**
+        Returns a suitable size hint for the given @e wxArtClient. If
+        @a platform_default is @true, return a size based on the current platform,
+        otherwise return the size from the topmost wxArtProvider. @e wxDefaultSize may
+        be returned if the client doesn't have a specified size, like wxART_OTHER for
+        example.
+    */
+    static wxSize GetSizeHint(const wxArtClient& client,
+                              bool platform_default = false);

 
     /**
         Query registered providers for icon bundle with given ID.
 
     /**
         Query registered providers for icon bundle with given ID.

-        
-        @param id 
-        wxArtID unique identifier of the icon bundle.
-        
-        @param client 
-        wxArtClient identifier of the client (i.e. who is asking for the icon bundle).
-        
+
+        @param id
+            wxArtID unique identifier of the icon bundle.
+        @param client
+            wxArtClient identifier of the client (i.e. who is asking for the icon
+            bundle).
+

         @returns The icon bundle if one of registered providers recognizes the ID
         @returns The icon bundle if one of registered providers recognizes the ID

-                   or wxNullIconBundle otherwise.
+                 or wxNullIconBundle otherwise.

     */
     static wxIconBundle GetIconBundle(const wxArtID& id,
                                       const wxArtClient& client = wxART_OTHER);
 
     /**
     */
     static wxIconBundle GetIconBundle(const wxArtID& id,
                                       const wxArtClient& client = wxART_OTHER);
 
     /**

-        Every bitmap and icon bundle are known to wxArtProvider under an unique ID that
-        is used when
-        requesting a resource from it. The ID is represented by wxArtID type and can
-        have one of these predefined values (you can see bitmaps represented by these
-        constants in the artprov sample):
-        
-         wxART_ERROR
-         wxART_QUESTION
-         wxART_WARNING
-         wxART_INFORMATION
-         wxART_ADD_BOOKMARK
-         wxART_DEL_BOOKMARK
-         wxART_HELP_SIDE_PANEL
-         wxART_HELP_SETTINGS
-         wxART_HELP_BOOK
-         wxART_HELP_FOLDER
-         wxART_HELP_PAGE
-         wxART_GO_BACK
-         wxART_GO_FORWARD
-         wxART_GO_UP
-         wxART_GO_DOWN
-         wxART_GO_TO_PARENT
-         wxART_GO_HOME
-         wxART_PRINT
-         wxART_HELP
-         wxART_TIP
-         wxART_REPORT_VIEW
-         wxART_LIST_VIEW
-         wxART_NEW_DIR
-         wxART_FOLDER
-         wxART_FOLDER_OPEN
-         wxART_GO_DIR_UP
-         wxART_EXECUTABLE_FILE
-         wxART_NORMAL_FILE
-         wxART_TICK_MARK
-         wxART_CROSS_MARK
-         wxART_MISSING_IMAGE
-         wxART_NEW
-         wxART_FILE_OPEN
-         wxART_FILE_SAVE
-         wxART_FILE_SAVE_AS
-         wxART_DELETE
-         wxART_COPY
-         wxART_CUT
-         wxART_PASTE
-         wxART_UNDO
-         wxART_REDO
-         wxART_QUIT
-         wxART_FIND
-         wxART_FIND_AND_REPLACE
-         wxART_HARDDISK
-         wxART_FLOPPY
-         wxART_CDROM
-         wxART_REMOVABLE
-        
-        Additionally, any string recognized by custom art providers registered using 
-        Push() may be used.
-    */
+        Register new art provider and add it to the bottom of providers stack
+        (i.e. it will be queried as the last one).

 
 

-
-    /**
-        Register new art provider and add it to the bottom of providers stack (i.e.
-        it will be queried as the last one).
-        
-        @sa Push()
+        @see Push()

     */
     static void Insert(wxArtProvider* provider);
 
     /**
         Remove latest added provider and delete it.
     */
     */
     static void Insert(wxArtProvider* provider);
 
     /**
         Remove latest added provider and delete it.
     */

-#define static bool Pop()     /* implementation is private */
+    static bool Pop();

 
     /**
 
     /**

-        Register new art provider and add it to the top of providers stack (i.e. it
-        will be queried as the first provider).
-        
-        @sa Insert()
+        Register new art provider and add it to the top of providers stack
+        (i.e. it will be queried as the first provider).
+
+        @see Insert()

     */
     static void Push(wxArtProvider* provider);
 
     /**
     */
     static void Push(wxArtProvider* provider);
 
     /**

-        Remove a provider from the stack if it is on it. The provider is not 
+        Remove a provider from the stack if it is on it. The provider is not

         deleted, unlike when using Delete().
     */
     static bool Remove(wxArtProvider* provider);
         deleted, unlike when using Delete().
     */
     static bool Remove(wxArtProvider* provider);

+
+protected:
+
+    /**
+        Derived art provider classes must override this method to create requested art
+        resource. Note that returned bitmaps are cached by wxArtProvider and it is
+        therefore not necessary to optimize CreateBitmap() for speed (e.g. you may
+        create wxBitmap objects from XPMs here).
+
+        @param id
+            wxArtID unique identifier of the bitmap.
+        @param client
+            wxArtClient identifier of the client (i.e. who is asking for the bitmap).
+            This only servers as a hint.
+        @param size
+            Preferred size of the bitmap. The function may return a bitmap of different
+            dimensions, it will be automatically rescaled to meet client's request.
+
+        @note
+        This is not part of wxArtProvider's public API, use wxArtProvider::GetBitmap
+        or wxArtProvider::GetIconBundle or wxArtProvider::GetIcon to query wxArtProvider
+        for a resource.
+
+        @see CreateIconBundle()
+    */
+    virtual wxBitmap CreateBitmap(const wxArtID& id,
+                                  const wxArtClient& client,
+                                  const wxSize& size);
+
+    /**
+        This method is similar to CreateBitmap() but can be used when a bitmap
+        (or an icon) exists in several sizes.
+    */
+    virtual wxIconBundle CreateIconBundle(const wxArtID& id,
+                                          const wxArtClient& client);

 };
 };

+