interface/wx/propgrid/editors.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        editors.h
   3 // Purpose:     interface of wxPropertyGrid editors
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id:
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 // -----------------------------------------------------------------------
  10
  11 /**
  12     @class wxPGEditor
  13
  14     Base class for custom wxPropertyGrid editors.
  15
  16     @remarks
  17     - Names of built-in property editors are: TextCtrl, Choice,
  18       ComboBox, CheckBox, TextCtrlAndButton, and ChoiceAndButton. Additional
  19       editors include SpinCtrl and DatePickerCtrl, but using them requires
  20       calling wxPropertyGrid::RegisterAdditionalEditors() prior use.
  21
  22     - Pointer to built-in editor is available as wxPGEditor_EditorName
  23       (eg. wxPGEditor_TextCtrl).
  24
  25     - Before you start using new editor you just created, you need to register
  26       it using static function
  27       wxPropertyGrid::RegisterEditorClass(), with code like this:
  28         @code
  29             wxPGEditor* editorPointer = wxPropertyGrid::RegisterEditorClass(new MyEditorClass(), "MyEditor");
  30         @endcode
  31       After that, wxPropertyGrid will take ownership of the given object, but
  32       you should still store editorPointer somewhere, so you can pass it to
  33       wxPGProperty::SetEditor(), or return it from wxPGEditor::DoGetEditorClass().
  34
  35     @library{wxpropgrid}
  36     @category{propgrid}
  37 */
  38 class wxPGEditor : public wxObject
  39 {
  40 public:
  41
  42     /** Constructor. */
  43     wxPGEditor()
  44         : wxObject()
  45     {
  46         m_clientData = NULL;
  47     }
  48
  49     /** Destructor. */
  50     virtual ~wxPGEditor();
  51
  52     /**
  53         Returns pointer to the name of the editor. For example,
  54         wxPGEditor_TextCtrl has name "TextCtrl".
  55     */
  56     virtual wxString GetName() const = 0;
  57
  58     /**
  59         Instantiates editor controls.
  60
  61         @param propgrid
  62             wxPropertyGrid to which the property belongs (use as parent for control).
  63
  64         @param property
  65             Property for which this method is called.
  66
  67         @param pos
  68             Position, inside wxPropertyGrid, to create control(s) to.
  69
  70         @param size
  71             Initial size for control(s).
  72
  73         @remarks
  74         - Primary control shall use id wxPG_SUBID1, and secondary (button) control
  75           shall use wxPG_SUBID2.
  76         - Implementation shoud connect all necessary events to the
  77           wxPropertyGrid::OnCustomEditorEvent. For Example:
  78             @code
  79                 // Relays wxEVT_COMMAND_TEXT_UPDATED events of primary editor
  80                 // control to the OnEvent.
  81                 control->Connect(control->GetId(), wxEVT_COMMAND_TEXT_UPDATED,
  82                                  wxCommandEventHandler(wxPropertyGrid::OnCustomEditorEvent),
  83                                  NULL, propgrid);
  84             @endcode
  85           OnCustomEditorEvent will then forward events, first to
  86           wxPGEditor::OnEvent() and then to wxPGProperty::OnEvent().
  87     */
  88     virtual wxPGWindowList CreateControls( wxPropertyGrid* propgrid,
  89                                            wxPGProperty* property,
  90                                            const wxPoint& pos,
  91                                            const wxSize& size ) const = 0;
  92
  93     /** Loads value from property to the control. */
  94     virtual void UpdateControl( wxPGProperty* property, wxWindow* ctrl ) const = 0;
  95
  96     /**
  97         Draws value for given property.
  98     */
  99     virtual void DrawValue( wxDC& dc, const wxRect& rect,
 100                             wxPGProperty* property, const wxString& text ) const;
 101
 102     /**
 103         Handles events. Returns @true if value in control was modified
 104         (see wxPGProperty::OnEvent() for more information).
 105     */
 106     virtual bool OnEvent( wxPropertyGrid* propgrid, wxPGProperty* property,
 107         wxWindow* wnd_primary, wxEvent& event ) const = 0;
 108
 109     /**
 110         Returns value from control, via parameter 'variant'.
 111         Usually ends up calling property's StringToValue() or IntToValue().
 112         Returns @true if value was different.
 113     */
 114     virtual bool GetValueFromControl( wxVariant& variant, wxPGProperty* property,
 115         wxWindow* ctrl ) const;
 116
 117     /** Sets value in control to unspecified. */
 118     virtual void SetValueToUnspecified( wxPGProperty* property,
 119         wxWindow* ctrl ) const = 0;
 120
 121     /** Sets control's value specifically from string. */
 122     virtual void SetControlStringValue( wxPGProperty* property,
 123         wxWindow* ctrl, const wxString& txt ) const;
 124
 125     /** Sets control's value specifically from int (applies to choice etc.). */
 126     virtual void SetControlIntValue( wxPGProperty* property,
 127         wxWindow* ctrl, int value ) const;
 128
 129     /**
 130         Inserts item to existing control. Index -1 means end of list.
 131         Default implementation does nothing. Returns index of item added.
 132     */
 133     virtual int InsertItem( wxWindow* ctrl, const wxString& label,
 134         int index ) const;
 135
 136     /**
 137         Deletes item from existing control.
 138         Default implementation does nothing.
 139     */
 140     virtual void DeleteItem( wxWindow* ctrl, int index ) const;
 141
 142     /**
 143         Extra processing when control gains focus. For example, wxTextCtrl
 144         based controls should select all text.
 145     */
 146     virtual void OnFocus( wxPGProperty* property, wxWindow* wnd ) const;
 147
 148     /**
 149         Returns @true if control itself can contain the custom image. Default
 150         implementation returns @false.
 151     */
 152     virtual bool CanContainCustomImage() const;
 153 };
 154
 155 // -----------------------------------------------------------------------
 156
 157 /**
 158     @class wxPGMultiButton
 159
 160     This class can be used to have multiple buttons in a property editor.
 161     You will need to create a new property editor class, override CreateControls,
 162     and have it return wxPGMultiButton instance in wxPGWindowList::SetSecondary().
 163
 164     For instance, here we add three buttons to a TextCtrl editor:
 165
 166     @code
 167
 168     #include <wx/propgrid/editors.h>
 169
 170     class wxSampleMultiButtonEditor : public wxPGTextCtrlEditor
 171     {
 172         DECLARE_DYNAMIC_CLASS(wxSampleMultiButtonEditor)
 173     public:
 174         wxSampleMultiButtonEditor() {}
 175         virtual ~wxSampleMultiButtonEditor() {}
 176
 177         virtual wxString GetName() const { return "SampleMultiButtonEditor"; }
 178
 179         virtual wxPGWindowList CreateControls( wxPropertyGrid* propGrid,
 180                                                wxPGProperty* property,
 181                                                const wxPoint& pos,
 182                                                const wxSize& sz ) const;
 183         virtual bool OnEvent( wxPropertyGrid* propGrid,
 184                               wxPGProperty* property,
 185                               wxWindow* ctrl,
 186                               wxEvent& event ) const;
 187     };
 188
 189     IMPLEMENT_DYNAMIC_CLASS(wxSampleMultiButtonEditor, wxPGTextCtrlEditor)
 190
 191     wxPGWindowList wxSampleMultiButtonEditor::CreateControls( wxPropertyGrid* propGrid,
 192                                                               wxPGProperty* property,
 193                                                               const wxPoint& pos,
 194                                                               const wxSize& sz ) const
 195     {
 196         // Create and populate buttons-subwindow
 197         wxPGMultiButton* buttons = new wxPGMultiButton( propGrid, sz );
 198
 199         // Add two regular buttons
 200         buttons->Add( "..." );
 201         buttons->Add( "A" );
 202         // Add a bitmap button
 203         buttons->Add( wxArtProvider::GetBitmap(wxART_FOLDER) );
 204
 205         // Create the 'primary' editor control (textctrl in this case)
 206         wxPGWindowList wndList = wxPGTextCtrlEditor::CreateControls
 207                                  ( propGrid, property, pos,
 208                                    buttons->GetPrimarySize() );
 209
 210         // Finally, move buttons-subwindow to correct position and make sure
 211         // returned wxPGWindowList contains our custom button list.
 212         buttons->Finalize(propGrid, pos);
 213
 214         wndList.SetSecondary( buttons );
 215         return wndList;
 216     }
 217
 218     bool wxSampleMultiButtonEditor::OnEvent( wxPropertyGrid* propGrid,
 219                                              wxPGProperty* property,
 220                                              wxWindow* ctrl,
 221                                              wxEvent& event ) const
 222     {
 223         if ( event.GetEventType() == wxEVT_COMMAND_BUTTON_CLICKED )
 224         {
 225             wxPGMultiButton* buttons = (wxPGMultiButton*) propGrid->GetEditorControlSecondary();
 226
 227             if ( event.GetId() == buttons->GetButtonId(0) )
 228             {
 229                 // Do something when first button is pressed
 230                 return true;
 231             }
 232             if ( event.GetId() == buttons->GetButtonId(1) )
 233             {
 234                 // Do something when second button is pressed
 235                 return true;
 236             }
 237             if ( event.GetId() == buttons->GetButtonId(2) )
 238             {
 239                 // Do something when third button is pressed
 240                 return true;
 241             }
 242         }
 243         return wxPGTextCtrlEditor::OnEvent(propGrid, property, ctrl, event);
 244     }
 245
 246     @endcode
 247
 248     Further to use this editor, code like this can be used:
 249
 250     @code
 251
 252         // Register editor class - needs only to be called once
 253         wxPGEditor* multiButtonEditor = new wxSampleMultiButtonEditor();
 254         wxPropertyGrid::RegisterEditorClass( multiButtonEditor );
 255
 256         // Insert the property that will have multiple buttons
 257         propGrid->Append( new wxLongStringProperty("MultipleButtons", wxPG_LABEL) );
 258
 259         // Change property to use editor created in the previous code segment
 260         propGrid->SetPropertyEditor( "MultipleButtons", multiButtonEditor );
 261
 262     @endcode
 263
 264     @library{wxpropgrid}
 265     @category{propgrid}
 266 */
 267 class WXDLLIMPEXP_PROPGRID wxPGMultiButton : public wxWindow
 268 {
 269 public:
 270
 271     /**
 272         Constructor.
 273     */
 274     wxPGMultiButton( wxPropertyGrid* pg, const wxSize& sz );
 275
 276     /**
 277         Destructor.
 278     */
 279     virtual ~wxPGMultiButton() { }
 280
 281     /**
 282         Adds new button, with given label.
 283     */
 284     void Add( const wxString& label, int id = -2 );
 285
 286     /**
 287         Adds new bitmap button.
 288     */
 289     void Add( const wxBitmap& bitmap, int id = -2 );
 290
 291     /**
 292         Call this in CreateControls() of your custom editor class
 293         after all buttons have been added.
 294
 295         @param propGrid
 296             wxPropertyGrid given in CreateControls().
 297
 298         @param pos
 299             wxPoint given in CreateControls().
 300     */
 301     void Finalize( wxPropertyGrid* propGrid, const wxPoint& pos );
 302
 303     /**
 304         Returns pointer to one of the buttons.
 305     */
 306     wxWindow* GetButton( unsigned int i );
 307
 308     /**
 309         Returns Id of one of the buttons. This is utility function to be
 310         used in event handlers.
 311     */
 312     int GetButtonId( unsigned int i ) const;
 313
 314     /**
 315         Returns number of buttons.
 316     */
 317     int GetCount();
 318
 319     /**
 320         Returns size of primary editor control, as appropriately
 321         reduced by number of buttons present.
 322     */
 323     wxSize GetPrimarySize() const;
 324 };
 325
 326 // -----------------------------------------------------------------------