docs/latex/wx/odcbox.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        odcbox.tex
   3 %% Purpose:     wxOwnerDrawnComboBox docs
   4 %% Author:      Jaakko Salli
   5 %% Modified by:
   6 %% Created:
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) Jaakko Salli
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxOwnerDrawnComboBox}}\label{wxownerdrawncombobox}
  13
  14 wxOwnerDrawnComboBox is a combobox with owner-drawn list items.
  15 In essence, it is a \helpref{wxComboCtrl}{wxcomboctrl} with
  16 \helpref{wxVListBox}{wxvlistbox} popup and \helpref{wxControlWithItems}{wxcontrolwithitems}
  17 interface.
  18
  19 Implementing item drawing and measuring is similar to \helpref{wxVListBox}{wxvlistbox}.
  20 Application needs to subclass wxOwnerDrawnComboBox and implement
  21 \helpref{OnDrawItem()}{wxownerdrawncomboboxondrawitem}, \helpref{OnMeasureItem()}{wxownerdrawncomboboxonmeasureitem}
  22 and \helpref{OnMeasureItemWidth()}{wxownerdrawncomboboxonmeasureitemwidth}.
  23
  24
  25 \wxheading{Derived from}
  26
  27 \helpref{wxComboCtrl}{wxcomboctrl}\\
  28 \helpref{wxControlWithItems}{wxcontrolwithitems}\\
  29 \helpref{wxControl}{wxcontrol}\\
  30 \helpref{wxWindow}{wxwindow}\\
  31 \helpref{wxEvtHandler}{wxevthandler}\\
  32 \helpref{wxObject}{wxobject}
  33
  34 \wxheading{Include files}
  35
  36 <odcombo.h>
  37
  38 \wxheading{Window styles}
  39
  40 \begin{twocollist}\itemsep=0pt
  41 \twocolitem{\windowstyle{wxODCB\_DCLICK\_CYCLES}}{Double-clicking cycles item
  42 if wxCB\_READONLY is also used. Synonymous with wxCC\_SPECIAL\_DCLICK.}
  43 \twocolitem{\windowstyle{wxODCB\_STD\_CONTROL\_PAINT}}{Control itself is not
  44 custom painted using OnDrawItem. Even if this style is not used, writable
  45 wxOwnerDrawnComboBox is never custom painted unless SetCustomPaintWidth is
  46 called.}
  47 \end{twocollist}
  48
  49 See also \helpref{wxComboCtrl window styles}{wxcomboctrl} and
  50 base \helpref{window styles overview}{windowstyles}.
  51
  52 \wxheading{Event handling}
  53
  54 \twocolwidtha{7cm}
  55 \begin{twocollist}\itemsep=0pt
  56 \twocolitem{{\bf EVT\_COMBOBOX(id, func)}}{Process a wxEVT\_COMMAND\_COMBOBOX\_SELECTED event,
  57 when an item on the list is selected. Note that calling
  58 \helpref{GetValue}{wxcomboctrlgetvalue} returns the new value of selection.}
  59 \end{twocollist}
  60
  61 See also events emitted by \helpref{wxComboCtrl}{wxcomboctrl}.
  62
  63 \wxheading{See also}
  64
  65 \helpref{wxComboCtrl}{wxcomboctrl}, \helpref{wxComboBox}{wxcombobox}, \helpref{wxVListBox}{wxvlistbox},
  66 \rtfsp\helpref{wxCommandEvent}{wxcommandevent}
  67
  68
  69 \latexignore{\rtfignore{\wxheading{Members}}}
  70
  71
  72 \membersection{wxOwnerDrawnComboBox::wxOwnerDrawnComboBox}\label{wxownerdrawncomboboxctor}
  73
  74 \func{}{wxOwnerDrawnComboBox}{\void}
  75
  76 Default constructor.
  77
  78 \func{}{wxOwnerDrawnComboBox}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
  79 \param{const wxString\& }{value = ``"}, \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
  80 \param{int}{ n = 0}, \param{const wxString }{choices[] = NULL},\rtfsp
  81 \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}
  82
  83 \func{}{wxOwnerDrawnComboBox}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
  84 \param{const wxString\& }{value}, \param{const wxPoint\&}{ pos}, \param{const wxSize\&}{ size},\rtfsp
  85 \param{const wxArrayString\& }{choices},\rtfsp
  86 \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}
  87
  88 Constructor, creating and showing a owner-drawn combobox.
  89
  90 \wxheading{Parameters}
  91
  92 \docparam{parent}{Parent window. Must not be NULL.}
  93
  94 \docparam{id}{Window identifier. A value of -1 indicates a default value.}
  95
  96 \docparam{value}{Initial selection string. An empty string indicates no selection.}
  97
  98 \docparam{pos}{Window position.}
  99
 100 \docparam{size}{Window size. If the default size (-1, -1) is specified then the window is sized
 101 appropriately.}
 102
 103 \docparam{n}{Number of strings with which to initialise the control.}
 104
 105 \docparam{choices}{An array of strings with which to initialise the control.}
 106
 107 \docparam{style}{Window style. See \helpref{wxOwnerDrawnComboBox}{wxownerdrawncombobox}.}
 108
 109 \docparam{validator}{Window validator.}
 110
 111 \docparam{name}{Window name.}
 112
 113 \wxheading{See also}
 114
 115 \helpref{wxOwnerDrawnComboBox::Create}{wxownerdrawncomboboxcreate}, \helpref{wxValidator}{wxvalidator}
 116
 117
 118 \membersection{wxOwnerDrawnComboBox::\destruct{wxOwnerDrawnComboBox}}\label{wxownerdrawncomboboxdtor}
 119
 120 \func{}{\destruct{wxOwnerDrawnComboBox}}{\void}
 121
 122 Destructor, destroying the owner-drawn combobox.
 123
 124
 125 \membersection{wxOwnerDrawnComboBox::Create}\label{wxownerdrawncomboboxcreate}
 126
 127 \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
 128 \param{const wxString\& }{value = ``"}, \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
 129 \param{int}{ n}, \param{const wxString }{choices[]},\rtfsp
 130 \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}
 131
 132 \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
 133 \param{const wxString\& }{value}, \param{const wxPoint\&}{ pos}, \param{const wxSize\&}{ size},\rtfsp
 134 \param{const wxArrayString\& }{choices},\rtfsp
 135 \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}
 136
 137 Creates the combobox for two-step construction. Derived classes
 138 should call or replace this function. See
 139 \helpref{wxOwnerDrawnComboBox::wxOwnerDrawnComboBox}{wxownerdrawncomboboxctor}\rtfsp
 140 for further details.
 141
 142
 143 \membersection{wxOwnerDrawnComboBox::OnDrawBackground}\label{wxownerdrawncomboboxondrawbackground}
 144
 145 \constfunc{void}{OnDrawBackground}{\param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{int }{item}, \param{int }{flags}}
 146
 147 This method is used to draw the items background and, maybe, a border around it.
 148
 149 The base class version implements a reasonable default behaviour which consists
 150 in drawing the selected item with the standard background colour and drawing a
 151 border around the item if it is either selected or current.
 152
 153 \wxheading{Remarks}
 154
 155 \arg{flags} has the same meaning as with \helpref{OnDrawItem}{wxownerdrawncomboboxondrawitem}.
 156
 157
 158 \membersection{wxOwnerDrawnComboBox::OnDrawItem}\label{wxownerdrawncomboboxondrawitem}
 159
 160 \constfunc{void}{OnDrawItem}{\param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{int }{item}, \param{int }{flags}}
 161
 162 The derived class may implement this function to actually draw the item
 163 with the given index on the provided DC. If function is not implemented,
 164 the item text is simply drawn, as if the control was a normal combobox.
 165
 166 \wxheading{Parameters}
 167
 168 \docparam{dc}{The device context to use for drawing}
 169
 170 \docparam{rect}{The bounding rectangle for the item being drawn (DC clipping
 171 region is set to this rectangle before calling this function)}
 172
 173 \docparam{item}{The index of the item to be drawn}
 174
 175 \docparam{flags}{Combines any of the following flag values:}
 176
 177 \twocolwidtha{7cm}%
 178 \begin{twocollist}\itemsep=0pt
 179 \twocolitem{{\tt wxODCB\_PAINTING\_CONTROL}}{Combo control is being
 180 painted, instead of a list item. Argument item may be wxNOT\_FOUND in this
 181 case.}
 182 \end{twocollist}
 183
 184
 185 \membersection{wxOwnerDrawnComboBox::OnMeasureItem}\label{wxownerdrawncomboboxonmeasureitem}
 186
 187 \constfunc{wxCoord}{OnMeasureItem}{\param{size\_t }{item}}
 188
 189 The derived class may implement this method to return the height of the
 190 specified item (in pixels).
 191
 192 The default implementation returns text height, as if this control was
 193 a normal combobox.
 194
 195
 196 \membersection{wxOwnerDrawnComboBox::OnMeasureItemWidth}\label{wxownerdrawncomboboxonmeasureitemwidth}
 197
 198 \constfunc{wxCoord}{OnMeasureItemWidth}{\param{size\_t }{item}}
 199
 200 The derived class may implement this method to return the width of the
 201 specified item (in pixels). If -1 is returned, then the item text width
 202 is used.
 203
 204 The default implementation returns -1.