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 licence
   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                  @c wxEVT_COMMAND_TEXT_ENTER is received and when it results in
  98                  property value being modified. This happens regardless of
  99                  editor type (ie. behaviour 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     /**
 118         Called by property grid to set new appearance for the control.
 119         Default implementation  sets foreground colour, background colour,
 120         font, plus text for wxTextCtrl and wxComboCtrl.
 121
 122         The parameter @a appearance represents the new appearance to be applied.
 123
 124         The parameter @a oldAppearance is the previously applied appearance.
 125         Used to detect which control attributes need to be changed (e.g. so we only
 126         change background colour if really needed).
 127
 128         Finally, the parameter @a unspecified if @true tells this function that
 129         the new appearance represents an unspecified property value.
 130     */
 131     virtual void SetControlAppearance( wxPropertyGrid* pg,
 132                                        wxPGProperty* property,
 133                                        wxWindow* ctrl,
 134                                        const wxPGCell& appearance,
 135                                        const wxPGCell& oldAppearance,
 136                                        bool unspecified ) const;
 137
 138     /** Sets control's value specifically from string. */
 139     virtual void SetControlStringValue( wxPGProperty* property,
 140                                         wxWindow* ctrl, const wxString& txt ) const;
 141
 142     /** Sets control's value specifically from int (applies to choice etc.). */
 143     virtual void SetControlIntValue( wxPGProperty* property,
 144                                      wxWindow* ctrl, int value ) const;
 145
 146     /**
 147         Inserts item to existing control. Index -1 means end of list.
 148         Default implementation does nothing. Returns index of item added.
 149     */
 150     virtual int InsertItem( wxWindow* ctrl, const wxString& label, int index ) const;
 151
 152     /**
 153         Deletes item from existing control.
 154         Default implementation does nothing.
 155     */
 156     virtual void DeleteItem( wxWindow* ctrl, int index ) const;
 157
 158     /**
 159         Extra processing when control gains focus.
 160         For example, wxTextCtrl based controls should select all text.
 161     */
 162     virtual void OnFocus( wxPGProperty* property, wxWindow* wnd ) const;
 163
 164     /**
 165         Returns @true if control itself can contain the custom image.
 166         Default implementation returns @false.
 167     */
 168     virtual bool CanContainCustomImage() const;
 169 };
 170
 171
 172
 173 /**
 174     @class wxPGMultiButton
 175
 176     This class can be used to have multiple buttons in a property editor.
 177     You will need to create a new property editor class, override CreateControls,
 178     and have it return wxPGMultiButton instance in wxPGWindowList::SetSecondary().
 179
 180     For instance, here we add three buttons to a TextCtrl editor:
 181
 182     @code
 183     #include <wx/propgrid/editors.h>
 184
 185     class wxSampleMultiButtonEditor : public wxPGTextCtrlEditor
 186     {
 187         wxDECLARE_DYNAMIC_CLASS(wxSampleMultiButtonEditor);
 188
 189     public:
 190         wxSampleMultiButtonEditor() {}
 191         virtual ~wxSampleMultiButtonEditor() {}
 192
 193         virtual wxString GetName() const { return "SampleMultiButtonEditor"; }
 194
 195         virtual wxPGWindowList CreateControls( wxPropertyGrid* propGrid,
 196                                                wxPGProperty* property,
 197                                                const wxPoint& pos,
 198                                                const wxSize& sz ) const;
 199         virtual bool OnEvent( wxPropertyGrid* propGrid,
 200                               wxPGProperty* property,
 201                               wxWindow* ctrl,
 202                               wxEvent& event ) const;
 203     };
 204
 205     wxIMPLEMENT_DYNAMIC_CLASS(wxSampleMultiButtonEditor, wxPGTextCtrlEditor);
 206
 207     wxPGWindowList wxSampleMultiButtonEditor::CreateControls( wxPropertyGrid* propGrid,
 208                                                               wxPGProperty* property,
 209                                                               const wxPoint& pos,
 210                                                               const wxSize& sz ) const
 211     {
 212         // Create and populate buttons-subwindow
 213         wxPGMultiButton* buttons = new wxPGMultiButton( propGrid, sz );
 214
 215         // Add two regular buttons
 216         buttons->Add( "..." );
 217         buttons->Add( "A" );
 218         // Add a bitmap button
 219         buttons->Add( wxArtProvider::GetBitmap(wxART_FOLDER) );
 220
 221         // Create the 'primary' editor control (textctrl in this case)
 222         wxPGWindowList wndList = wxPGTextCtrlEditor::CreateControls
 223                                  ( propGrid, property, pos,
 224                                    buttons->GetPrimarySize() );
 225
 226         // Finally, move buttons-subwindow to correct position and make sure
 227         // returned wxPGWindowList contains our custom button list.
 228         buttons->Finalize(propGrid, pos);
 229
 230         wndList.SetSecondary( buttons );
 231         return wndList;
 232     }
 233
 234     bool wxSampleMultiButtonEditor::OnEvent( wxPropertyGrid* propGrid,
 235                                              wxPGProperty* property,
 236                                              wxWindow* ctrl,
 237                                              wxEvent& event ) const
 238     {
 239         if ( event.GetEventType() == wxEVT_COMMAND_BUTTON_CLICKED )
 240         {
 241             wxPGMultiButton* buttons = (wxPGMultiButton*) propGrid->GetEditorControlSecondary();
 242
 243             if ( event.GetId() == buttons->GetButtonId(0) )
 244             {
 245                 // Do something when the first button is pressed
 246                 // Return true if the action modified the value in editor.
 247                 ...
 248             }
 249             if ( event.GetId() == buttons->GetButtonId(1) )
 250             {
 251                 // Do something when the second button is pressed
 252                 ...
 253             }
 254             if ( event.GetId() == buttons->GetButtonId(2) )
 255             {
 256                 // Do something when the third button is pressed
 257                 ...
 258             }
 259         }
 260         return wxPGTextCtrlEditor::OnEvent(propGrid, property, ctrl, event);
 261     }
 262     @endcode
 263
 264     Further to use this editor, code like this can be used:
 265
 266     @code
 267         // Register editor class - needs only to be called once
 268         wxPGEditor* multiButtonEditor = new wxSampleMultiButtonEditor();
 269         wxPropertyGrid::RegisterEditorClass( multiButtonEditor );
 270
 271         // Insert the property that will have multiple buttons
 272         propGrid->Append( new wxLongStringProperty("MultipleButtons", wxPG_LABEL) );
 273
 274         // Change property to use editor created in the previous code segment
 275         propGrid->SetPropertyEditor( "MultipleButtons", multiButtonEditor );
 276     @endcode
 277
 278     @library{wxpropgrid}
 279     @category{propgrid}
 280 */
 281 class WXDLLIMPEXP_PROPGRID wxPGMultiButton : public wxWindow
 282 {
 283 public:
 284     /**
 285         Constructor.
 286     */
 287     wxPGMultiButton( wxPropertyGrid* pg, const wxSize& sz );
 288
 289     /**
 290         Destructor.
 291     */
 292     virtual ~wxPGMultiButton() { }
 293
 294     /**
 295         Adds new button, with given label.
 296     */
 297     void Add( const wxString& label, int id = -2 );
 298
 299     /**
 300         Adds new bitmap button.
 301     */
 302     void Add( const wxBitmap& bitmap, int id = -2 );
 303
 304     /**
 305         Call this in CreateControls() of your custom editor class
 306         after all buttons have been added.
 307
 308         @param propGrid
 309             wxPropertyGrid given in CreateControls().
 310
 311         @param pos
 312             wxPoint given in CreateControls().
 313     */
 314     void Finalize( wxPropertyGrid* propGrid, const wxPoint& pos );
 315
 316     /**
 317         Returns pointer to one of the buttons.
 318     */
 319     wxWindow* GetButton( unsigned int i );
 320
 321     /**
 322         Returns Id of one of the buttons.
 323         This is utility function to be used in event handlers.
 324     */
 325     int GetButtonId( unsigned int i ) const;
 326
 327     /**
 328         Returns number of buttons.
 329     */
 330     unsigned int GetCount();
 331
 332     /**
 333         Returns size of primary editor control, as appropriately
 334         reduced by number of buttons present.
 335     */
 336     wxSize GetPrimarySize() const;
 337 };
 338