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