]> git.saurik.com Git - wxWidgets.git/blob - src/msw/menu.cpp
typofix
[wxWidgets.git] / src / msw / menu.cpp
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: src/msw/menu.cpp
3 // Purpose: wxMenu, wxMenuBar, wxMenuItem
4 // Author: Julian Smart
5 // Modified by: Vadim Zeitlin
6 // Created: 04/01/98
7 // RCS-ID: $Id$
8 // Copyright: (c) Julian Smart
9 // Licence: wxWindows licence
10 /////////////////////////////////////////////////////////////////////////////
11
12 // ===========================================================================
13 // declarations
14 // ===========================================================================
15
16 // ---------------------------------------------------------------------------
17 // headers
18 // ---------------------------------------------------------------------------
19
20 // For compilers that support precompilation, includes "wx.h".
21 #include "wx/wxprec.h"
22
23 #ifdef __BORLANDC__
24 #pragma hdrstop
25 #endif
26
27 #if wxUSE_MENUS
28
29 #include "wx/menu.h"
30
31 #ifndef WX_PRECOMP
32 #include "wx/msw/wrapcctl.h" // include <commctrl.h> "properly"
33 #include "wx/frame.h"
34 #include "wx/utils.h"
35 #include "wx/intl.h"
36 #include "wx/log.h"
37 #endif
38
39 #if wxUSE_OWNER_DRAWN
40 #include "wx/ownerdrw.h"
41 #endif
42
43 #include "wx/msw/private.h"
44
45 #ifdef __WXWINCE__
46 #include <windows.h>
47 #include <windowsx.h>
48 #include <tchar.h>
49 #include <ole2.h>
50 #include <shellapi.h>
51 #if (_WIN32_WCE < 400) && !defined(__HANDHELDPC__)
52 #include <aygshell.h>
53 #endif
54
55 #include "wx/msw/wince/missing.h"
56
57 #endif
58
59 // other standard headers
60 #include <string.h>
61
62 //VC6 needs these defining, though they are in winuser.h
63 #ifndef MIIM_BITMAP
64 #define MIIM_STRING 0x00000040
65 #define MIIM_BITMAP 0x00000080
66 #define MIIM_FTYPE 0x00000100
67 #define HBMMENU_CALLBACK ((HBITMAP) -1)
68 typedef struct tagMENUINFO
69 {
70 DWORD cbSize;
71 DWORD fMask;
72 DWORD dwStyle;
73 UINT cyMax;
74 HBRUSH hbrBack;
75 DWORD dwContextHelpID;
76 DWORD dwMenuData;
77 } MENUINFO, FAR *LPMENUINFO;
78 #endif
79
80 #if wxUSE_OWNER_DRAWN
81 #include "wx/dynlib.h"
82 #endif
83
84 #ifndef MNS_CHECKORBMP
85 #define MNS_CHECKORBMP 0x04000000
86 #endif
87 #ifndef MIM_STYLE
88 #define MIM_STYLE 0x00000010
89 #endif
90
91 // ----------------------------------------------------------------------------
92 // global variables
93 // ----------------------------------------------------------------------------
94
95 // ----------------------------------------------------------------------------
96 // constants
97 // ----------------------------------------------------------------------------
98
99 // the (popup) menu title has this special id
100 static const UINT idMenuTitle = (UINT)-3;
101
102 // ----------------------------------------------------------------------------
103 // private functions
104 // ----------------------------------------------------------------------------
105
106 // make the given menu item default
107 static void SetDefaultMenuItem(HMENU WXUNUSED_IN_WINCE(hmenu),
108 UINT WXUNUSED_IN_WINCE(id))
109 {
110 #ifndef __WXWINCE__
111 MENUITEMINFO mii;
112 wxZeroMemory(mii);
113 mii.cbSize = sizeof(MENUITEMINFO);
114 mii.fMask = MIIM_STATE;
115 mii.fState = MFS_DEFAULT;
116
117 if ( !::SetMenuItemInfo(hmenu, id, FALSE, &mii) )
118 {
119 wxLogLastError(wxT("SetMenuItemInfo"));
120 }
121 #endif
122 }
123
124 #ifdef __WXWINCE__
125 UINT GetMenuState(HMENU hMenu, UINT id, UINT flags)
126 {
127 MENUITEMINFO info;
128 wxZeroMemory(info);
129 info.cbSize = sizeof(info);
130 info.fMask = MIIM_STATE;
131 // MF_BYCOMMAND is zero so test MF_BYPOSITION
132 if ( !::GetMenuItemInfo(hMenu, id, flags & MF_BYPOSITION ? TRUE : FALSE , & info) )
133 wxLogLastError(wxT("GetMenuItemInfo"));
134 return info.fState;
135 }
136 #endif
137
138 // ============================================================================
139 // implementation
140 // ============================================================================
141
142 #include "wx/listimpl.cpp"
143
144 WX_DEFINE_LIST( wxMenuInfoList )
145
146 #if wxUSE_EXTENDED_RTTI
147
148 WX_DEFINE_FLAGS( wxMenuStyle )
149
150 wxBEGIN_FLAGS( wxMenuStyle )
151 wxFLAGS_MEMBER(wxMENU_TEAROFF)
152 wxEND_FLAGS( wxMenuStyle )
153
154 IMPLEMENT_DYNAMIC_CLASS_XTI(wxMenu, wxEvtHandler,"wx/menu.h")
155
156 wxCOLLECTION_TYPE_INFO( wxMenuItem * , wxMenuItemList ) ;
157
158 template<> void wxCollectionToVariantArray( wxMenuItemList const &theList, wxxVariantArray &value)
159 {
160 wxListCollectionToVariantArray<wxMenuItemList::compatibility_iterator>( theList , value ) ;
161 }
162
163 wxBEGIN_PROPERTIES_TABLE(wxMenu)
164 wxEVENT_PROPERTY( Select , wxEVT_COMMAND_MENU_SELECTED , wxCommandEvent)
165 wxPROPERTY( Title, wxString , SetTitle, GetTitle, wxString(), 0 /*flags*/ , wxT("Helpstring") , wxT("group") )
166 wxREADONLY_PROPERTY_FLAGS( MenuStyle , wxMenuStyle , long , GetStyle , EMPTY_MACROVALUE , 0 /*flags*/ , wxT("Helpstring") , wxT("group")) // style
167 wxPROPERTY_COLLECTION( MenuItems , wxMenuItemList , wxMenuItem* , Append , GetMenuItems , 0 /*flags*/ , wxT("Helpstring") , wxT("group"))
168 wxEND_PROPERTIES_TABLE()
169
170 wxBEGIN_HANDLERS_TABLE(wxMenu)
171 wxEND_HANDLERS_TABLE()
172
173 wxDIRECT_CONSTRUCTOR_2( wxMenu , wxString , Title , long , MenuStyle )
174
175 WX_DEFINE_FLAGS( wxMenuBarStyle )
176
177 wxBEGIN_FLAGS( wxMenuBarStyle )
178 wxFLAGS_MEMBER(wxMB_DOCKABLE)
179 wxEND_FLAGS( wxMenuBarStyle )
180
181 // the negative id would lead the window (its superclass !) to vetoe streaming out otherwise
182 bool wxMenuBarStreamingCallback( const wxObject *WXUNUSED(object), wxWriter * , wxPersister * , wxxVariantArray & )
183 {
184 return true ;
185 }
186
187 IMPLEMENT_DYNAMIC_CLASS_XTI_CALLBACK(wxMenuBar, wxWindow ,"wx/menu.h",wxMenuBarStreamingCallback)
188
189 IMPLEMENT_DYNAMIC_CLASS_XTI(wxMenuInfo, wxObject , "wx/menu.h" )
190
191 wxBEGIN_PROPERTIES_TABLE(wxMenuInfo)
192 wxREADONLY_PROPERTY( Menu , wxMenu* , GetMenu , EMPTY_MACROVALUE , 0 /*flags*/ , wxT("Helpstring") , wxT("group"))
193 wxREADONLY_PROPERTY( Title , wxString , GetTitle , wxString() , 0 /*flags*/ , wxT("Helpstring") , wxT("group"))
194 wxEND_PROPERTIES_TABLE()
195
196 wxBEGIN_HANDLERS_TABLE(wxMenuInfo)
197 wxEND_HANDLERS_TABLE()
198
199 wxCONSTRUCTOR_2( wxMenuInfo , wxMenu* , Menu , wxString , Title )
200
201 wxCOLLECTION_TYPE_INFO( wxMenuInfo * , wxMenuInfoList ) ;
202
203 template<> void wxCollectionToVariantArray( wxMenuInfoList const &theList, wxxVariantArray &value)
204 {
205 wxListCollectionToVariantArray<wxMenuInfoList::compatibility_iterator>( theList , value ) ;
206 }
207
208 wxBEGIN_PROPERTIES_TABLE(wxMenuBar)
209 wxPROPERTY_COLLECTION( MenuInfos , wxMenuInfoList , wxMenuInfo* , Append , GetMenuInfos , 0 /*flags*/ , wxT("Helpstring") , wxT("group"))
210 wxEND_PROPERTIES_TABLE()
211
212 wxBEGIN_HANDLERS_TABLE(wxMenuBar)
213 wxEND_HANDLERS_TABLE()
214
215 wxCONSTRUCTOR_DUMMY( wxMenuBar )
216
217 #else
218 IMPLEMENT_DYNAMIC_CLASS(wxMenu, wxEvtHandler)
219 IMPLEMENT_DYNAMIC_CLASS(wxMenuBar, wxWindow)
220 IMPLEMENT_DYNAMIC_CLASS(wxMenuInfo, wxObject)
221 #endif
222
223 const wxMenuInfoList& wxMenuBar::GetMenuInfos() const
224 {
225 wxMenuInfoList* list = const_cast< wxMenuInfoList* >( &m_menuInfos ) ;
226 WX_CLEAR_LIST( wxMenuInfoList , *list ) ;
227 for( size_t i = 0 ; i < GetMenuCount() ; ++i )
228 {
229 wxMenuInfo* info = new wxMenuInfo() ;
230 info->Create( const_cast<wxMenuBar*>(this)->GetMenu(i) , GetMenuLabel(i) ) ;
231 list->Append( info ) ;
232 }
233 return m_menuInfos ;
234 }
235
236 // ---------------------------------------------------------------------------
237 // wxMenu construction, adding and removing menu items
238 // ---------------------------------------------------------------------------
239
240 // Construct a menu with optional title (then use append)
241 void wxMenu::Init()
242 {
243 m_doBreak = false;
244 m_startRadioGroup = -1;
245
246 // create the menu
247 m_hMenu = (WXHMENU)CreatePopupMenu();
248 if ( !m_hMenu )
249 {
250 wxLogLastError(wxT("CreatePopupMenu"));
251 }
252
253 // if we have a title, insert it in the beginning of the menu
254 if ( !m_title.empty() )
255 {
256 Append(idMenuTitle, m_title);
257 AppendSeparator();
258 }
259 }
260
261 // The wxWindow destructor will take care of deleting the submenus.
262 wxMenu::~wxMenu()
263 {
264 // we should free Windows resources only if Windows doesn't do it for us
265 // which happens if we're attached to a menubar or a submenu of another
266 // menu
267 if ( !IsAttached() && !GetParent() )
268 {
269 if ( !::DestroyMenu(GetHmenu()) )
270 {
271 wxLogLastError(wxT("DestroyMenu"));
272 }
273 }
274
275 #if wxUSE_ACCEL
276 // delete accels
277 WX_CLEAR_ARRAY(m_accels);
278 #endif // wxUSE_ACCEL
279 }
280
281 void wxMenu::Break()
282 {
283 // this will take effect during the next call to Append()
284 m_doBreak = true;
285 }
286
287 void wxMenu::Attach(wxMenuBarBase *menubar)
288 {
289 wxMenuBase::Attach(menubar);
290
291 EndRadioGroup();
292 }
293
294 #if wxUSE_ACCEL
295
296 int wxMenu::FindAccel(int id) const
297 {
298 size_t n, count = m_accels.GetCount();
299 for ( n = 0; n < count; n++ )
300 {
301 if ( m_accels[n]->m_command == id )
302 return n;
303 }
304
305 return wxNOT_FOUND;
306 }
307
308 void wxMenu::UpdateAccel(wxMenuItem *item)
309 {
310 if ( item->IsSubMenu() )
311 {
312 wxMenu *submenu = item->GetSubMenu();
313 wxMenuItemList::compatibility_iterator node = submenu->GetMenuItems().GetFirst();
314 while ( node )
315 {
316 UpdateAccel(node->GetData());
317
318 node = node->GetNext();
319 }
320 }
321 else if ( !item->IsSeparator() )
322 {
323 // recurse upwards: we should only modify m_accels of the top level
324 // menus, not of the submenus as wxMenuBar doesn't look at them
325 // (alternative and arguable cleaner solution would be to recurse
326 // downwards in GetAccelCount() and CopyAccels())
327 if ( GetParent() )
328 {
329 GetParent()->UpdateAccel(item);
330 return;
331 }
332
333 // find the (new) accel for this item
334 wxAcceleratorEntry *accel = wxAcceleratorEntry::Create(item->GetItemLabel());
335 if ( accel )
336 accel->m_command = item->GetId();
337
338 // find the old one
339 int n = FindAccel(item->GetId());
340 if ( n == wxNOT_FOUND )
341 {
342 // no old, add new if any
343 if ( accel )
344 m_accels.Add(accel);
345 else
346 return; // skipping RebuildAccelTable() below
347 }
348 else
349 {
350 // replace old with new or just remove the old one if no new
351 delete m_accels[n];
352 if ( accel )
353 m_accels[n] = accel;
354 else
355 m_accels.RemoveAt(n);
356 }
357
358 if ( IsAttached() )
359 {
360 GetMenuBar()->RebuildAccelTable();
361 }
362 }
363 //else: it is a separator, they can't have accels, nothing to do
364 }
365
366 #endif // wxUSE_ACCEL
367
368 // append a new item or submenu to the menu
369 bool wxMenu::DoInsertOrAppend(wxMenuItem *pItem, size_t pos)
370 {
371 #if wxUSE_ACCEL
372 UpdateAccel(pItem);
373 #endif // wxUSE_ACCEL
374
375 UINT flags = 0;
376
377 // if "Break" has just been called, insert a menu break before this item
378 // (and don't forget to reset the flag)
379 if ( m_doBreak ) {
380 flags |= MF_MENUBREAK;
381 m_doBreak = false;
382 }
383
384 if ( pItem->IsSeparator() ) {
385 flags |= MF_SEPARATOR;
386 }
387
388 // id is the numeric id for normal menu items and HMENU for submenus as
389 // required by ::AppendMenu() API
390 UINT_PTR id;
391 wxMenu *submenu = pItem->GetSubMenu();
392 if ( submenu != NULL ) {
393 wxASSERT_MSG( submenu->GetHMenu(), wxT("invalid submenu") );
394
395 submenu->SetParent(this);
396
397 id = (UINT_PTR)submenu->GetHMenu();
398
399 flags |= MF_POPUP;
400 }
401 else {
402 id = pItem->GetMSWId();
403 }
404
405
406 // prepare to insert the item in the menu
407 wxString itemText = pItem->GetItemLabel();
408 LPCTSTR pData = NULL;
409 if ( pos == (size_t)-1 )
410 {
411 // append at the end (note that the item is already appended to
412 // internal data structures)
413 pos = GetMenuItemCount() - 1;
414 }
415
416 // adjust position to account for the title, if any
417 if ( !m_title.empty() )
418 pos += 2; // for the title itself and its separator
419
420 BOOL ok = false;
421
422 #if wxUSE_OWNER_DRAWN
423 // Currently, mixing owner-drawn and non-owner-drawn items results in
424 // inconsistent margins, so we force this to be owner-drawn if any other
425 // items already are. Later we might want to use a boolean in the wxMenu
426 // to avoid search. Also we might make this fix unnecessary by getting the correct
427 // margin using NONCLIENTMETRICS.
428 if ( !pItem->IsOwnerDrawn() && !pItem->IsSeparator() )
429 {
430 // Check if any other items are ownerdrawn, and make ownerdrawn if so
431 wxMenuItemList::compatibility_iterator node = GetMenuItems().GetFirst();
432 while (node)
433 {
434 if (node->GetData()->IsOwnerDrawn())
435 {
436 pItem->SetOwnerDrawn(true);
437 break;
438 }
439 node = node->GetNext();
440 }
441 }
442 #endif
443
444 // check if we have something more than a simple text item
445 #if wxUSE_OWNER_DRAWN
446 if ( pItem->IsOwnerDrawn() )
447 {
448 // is the item owner-drawn just because of the [checked] bitmap?
449 if ( (pItem->GetBitmap(false).Ok() || pItem->GetBitmap(true).Ok()) &&
450 !pItem->GetTextColour().Ok() &&
451 !pItem->GetBackgroundColour().Ok() &&
452 !pItem->GetFont().Ok() )
453 {
454 // try to use InsertMenuItem() as it's guaranteed to look correct
455 // while our owner-drawn code is not
456 #ifndef __DMC__
457 // DMC at march 2007 doesn't have HBITMAP hbmpItem tagMENUITEMINFOA /W
458 // MIIM_BITMAP only works under WinME/2000+
459 WinStruct<MENUITEMINFO> mii;
460 if ( wxGetWinVersion() >= wxWinVersion_98 )
461 {
462 mii.fMask = MIIM_STRING | MIIM_DATA | MIIM_BITMAP;
463 if ( pItem->IsCheckable() )
464 {
465 // need to set checked/unchecked bitmaps as otherwise our
466 // MSWOnDrawItem() item is not called
467 mii.fMask |= MIIM_CHECKMARKS;
468 }
469
470 mii.cch = itemText.length();
471 mii.dwTypeData = wx_const_cast(wxChar *, itemText.wx_str());
472
473 if (flags & MF_POPUP)
474 {
475 mii.fMask |= MIIM_SUBMENU;
476 mii.hSubMenu = (HMENU)pItem->GetSubMenu()->GetHMenu();
477 }
478 else
479 {
480 mii.fMask |= MIIM_ID;
481 mii.wID = id;
482 }
483
484 // we can't pass HBITMAP directly as hbmpItem for 2 reasons:
485 // 1. we can't draw it with transparency then (this is not
486 // very important now but would be with themed menu bg)
487 // 2. worse, Windows inverts the bitmap for the selected
488 // item and this looks downright ugly
489 //
490 // so instead draw it ourselves in MSWOnDrawItem()
491 mii.dwItemData = wx_reinterpret_cast(ULONG_PTR, pItem);
492 if ( pItem->IsCheckable() )
493 {
494 mii.hbmpChecked =
495 mii.hbmpUnchecked = HBMMENU_CALLBACK;
496 }
497 mii.hbmpItem = HBMMENU_CALLBACK;
498
499 ok = ::InsertMenuItem(GetHmenu(), pos, TRUE /* by pos */, &mii);
500 if ( !ok )
501 {
502 wxLogLastError(wxT("InsertMenuItem()"));
503 }
504 else // InsertMenuItem() ok
505 {
506 // we need to remove the extra indent which is reserved for
507 // the checkboxes by default as it looks ugly unless check
508 // boxes are used together with bitmaps and this is not the
509 // case in wx API
510 WinStruct<MENUINFO> mi;
511
512 // don't call SetMenuInfo() directly, this would prevent
513 // the app from starting up under Windows 95/NT 4
514 typedef BOOL (WINAPI *SetMenuInfo_t)(HMENU, MENUINFO *);
515
516 wxDynamicLibrary dllUser(_T("user32"));
517 wxDYNLIB_FUNCTION(SetMenuInfo_t, SetMenuInfo, dllUser);
518 if ( pfnSetMenuInfo )
519 {
520 mi.fMask = MIM_STYLE;
521 mi.dwStyle = MNS_CHECKORBMP;
522 if ( !(*pfnSetMenuInfo)(GetHmenu(), &mi) )
523 wxLogLastError(_T("SetMenuInfo(MNS_NOCHECK)"));
524 }
525
526 // tell the item that it's not really owner-drawn but only
527 // needs to draw its bitmap, the rest is done by Windows
528 pItem->ResetOwnerDrawn();
529 }
530 }
531 #endif // __DMC__
532 }
533
534 if ( !ok )
535 {
536 // item draws itself, pass pointer to it in data parameter
537 flags |= MF_OWNERDRAW;
538 pData = (LPCTSTR)pItem;
539 }
540 }
541 else
542 #endif // wxUSE_OWNER_DRAWN
543 {
544 // item is just a normal string (passed in data parameter)
545 flags |= MF_STRING;
546
547 #ifdef __WXWINCE__
548 itemText = wxMenuItem::GetLabelText(itemText);
549 #endif
550
551 pData = (wxChar*)itemText.wx_str();
552 }
553
554 // item might have already been inserted by InsertMenuItem() above
555 if ( !ok )
556 {
557 if ( !::InsertMenu(GetHmenu(), pos, flags | MF_BYPOSITION, id, pData) )
558 {
559 wxLogLastError(wxT("InsertMenu[Item]()"));
560
561 return false;
562 }
563 }
564
565
566 // if we just appended the title, highlight it
567 if ( id == idMenuTitle )
568 {
569 // visually select the menu title
570 SetDefaultMenuItem(GetHmenu(), id);
571 }
572
573 // if we're already attached to the menubar, we must update it
574 if ( IsAttached() && GetMenuBar()->IsAttached() )
575 {
576 GetMenuBar()->Refresh();
577 }
578
579 return true;
580 }
581
582 void wxMenu::EndRadioGroup()
583 {
584 // we're not inside a radio group any longer
585 m_startRadioGroup = -1;
586 }
587
588 wxMenuItem* wxMenu::DoAppend(wxMenuItem *item)
589 {
590 wxCHECK_MSG( item, NULL, _T("NULL item in wxMenu::DoAppend") );
591
592 bool check = false;
593
594 if ( item->GetKind() == wxITEM_RADIO )
595 {
596 int count = GetMenuItemCount();
597
598 if ( m_startRadioGroup == -1 )
599 {
600 // start a new radio group
601 m_startRadioGroup = count;
602
603 // for now it has just one element
604 item->SetAsRadioGroupStart();
605 item->SetRadioGroupEnd(m_startRadioGroup);
606
607 // ensure that we have a checked item in the radio group
608 check = true;
609 }
610 else // extend the current radio group
611 {
612 // we need to update its end item
613 item->SetRadioGroupStart(m_startRadioGroup);
614 wxMenuItemList::compatibility_iterator node = GetMenuItems().Item(m_startRadioGroup);
615
616 if ( node )
617 {
618 node->GetData()->SetRadioGroupEnd(count);
619 }
620 else
621 {
622 wxFAIL_MSG( _T("where is the radio group start item?") );
623 }
624 }
625 }
626 else // not a radio item
627 {
628 EndRadioGroup();
629 }
630
631 if ( !wxMenuBase::DoAppend(item) || !DoInsertOrAppend(item) )
632 {
633 return NULL;
634 }
635
636 if ( check )
637 {
638 // check the item initially
639 item->Check(true);
640 }
641
642 return item;
643 }
644
645 wxMenuItem* wxMenu::DoInsert(size_t pos, wxMenuItem *item)
646 {
647 if (wxMenuBase::DoInsert(pos, item) && DoInsertOrAppend(item, pos))
648 return item;
649 else
650 return NULL;
651 }
652
653 wxMenuItem *wxMenu::DoRemove(wxMenuItem *item)
654 {
655 // we need to find the item's position in the child list
656 size_t pos;
657 wxMenuItemList::compatibility_iterator node = GetMenuItems().GetFirst();
658 for ( pos = 0; node; pos++ )
659 {
660 if ( node->GetData() == item )
661 break;
662
663 node = node->GetNext();
664 }
665
666 // DoRemove() (unlike Remove) can only be called for an existing item!
667 wxCHECK_MSG( node, NULL, wxT("bug in wxMenu::Remove logic") );
668
669 #if wxUSE_ACCEL
670 // remove the corresponding accel from the accel table
671 int n = FindAccel(item->GetId());
672 if ( n != wxNOT_FOUND )
673 {
674 delete m_accels[n];
675
676 m_accels.RemoveAt(n);
677 }
678 //else: this item doesn't have an accel, nothing to do
679 #endif // wxUSE_ACCEL
680
681 // remove the item from the menu
682 if ( !::RemoveMenu(GetHmenu(), (UINT)pos, MF_BYPOSITION) )
683 {
684 wxLogLastError(wxT("RemoveMenu"));
685 }
686
687 if ( IsAttached() && GetMenuBar()->IsAttached() )
688 {
689 // otherwise, the change won't be visible
690 GetMenuBar()->Refresh();
691 }
692
693 // and from internal data structures
694 return wxMenuBase::DoRemove(item);
695 }
696
697 // ---------------------------------------------------------------------------
698 // accelerator helpers
699 // ---------------------------------------------------------------------------
700
701 #if wxUSE_ACCEL
702
703 // create the wxAcceleratorEntries for our accels and put them into the provided
704 // array - return the number of accels we have
705 size_t wxMenu::CopyAccels(wxAcceleratorEntry *accels) const
706 {
707 size_t count = GetAccelCount();
708 for ( size_t n = 0; n < count; n++ )
709 {
710 *accels++ = *m_accels[n];
711 }
712
713 return count;
714 }
715
716 #endif // wxUSE_ACCEL
717
718 // ---------------------------------------------------------------------------
719 // set wxMenu title
720 // ---------------------------------------------------------------------------
721
722 void wxMenu::SetTitle(const wxString& label)
723 {
724 bool hasNoTitle = m_title.empty();
725 m_title = label;
726
727 HMENU hMenu = GetHmenu();
728
729 if ( hasNoTitle )
730 {
731 if ( !label.empty() )
732 {
733 if ( !::InsertMenu(hMenu, 0u, MF_BYPOSITION | MF_STRING,
734 idMenuTitle, m_title.wx_str()) ||
735 !::InsertMenu(hMenu, 1u, MF_BYPOSITION, (unsigned)-1, NULL) )
736 {
737 wxLogLastError(wxT("InsertMenu"));
738 }
739 }
740 }
741 else
742 {
743 if ( label.empty() )
744 {
745 // remove the title and the separator after it
746 if ( !RemoveMenu(hMenu, 0, MF_BYPOSITION) ||
747 !RemoveMenu(hMenu, 0, MF_BYPOSITION) )
748 {
749 wxLogLastError(wxT("RemoveMenu"));
750 }
751 }
752 else
753 {
754 // modify the title
755 #ifdef __WXWINCE__
756 MENUITEMINFO info;
757 wxZeroMemory(info);
758 info.cbSize = sizeof(info);
759 info.fMask = MIIM_TYPE;
760 info.fType = MFT_STRING;
761 info.cch = m_title.length();
762 info.dwTypeData = wx_const_cast(wxChar *, m_title.wx_str());
763 if ( !SetMenuItemInfo(hMenu, 0, TRUE, & info) )
764 {
765 wxLogLastError(wxT("SetMenuItemInfo"));
766 }
767 #else
768 if ( !ModifyMenu(hMenu, 0u,
769 MF_BYPOSITION | MF_STRING,
770 idMenuTitle, m_title.wx_str()) )
771 {
772 wxLogLastError(wxT("ModifyMenu"));
773 }
774 #endif
775 }
776 }
777
778 #ifdef __WIN32__
779 // put the title string in bold face
780 if ( !m_title.empty() )
781 {
782 SetDefaultMenuItem(GetHmenu(), idMenuTitle);
783 }
784 #endif // Win32
785 }
786
787 // ---------------------------------------------------------------------------
788 // event processing
789 // ---------------------------------------------------------------------------
790
791 bool wxMenu::MSWCommand(WXUINT WXUNUSED(param), WXWORD id_)
792 {
793 const int id = (signed short)id_;
794
795 // ignore commands from the menu title
796 if ( id != (int)idMenuTitle )
797 {
798 // update the check item when it's clicked
799 wxMenuItem * const item = FindItem(id);
800 if ( item && item->IsCheckable() )
801 item->Toggle();
802
803 // get the status of the menu item: note that it has been just changed
804 // by Toggle() above so here we already get the new state of the item
805 UINT menuState = ::GetMenuState(GetHmenu(), id, MF_BYCOMMAND);
806 SendEvent(id, menuState & MF_CHECKED);
807 }
808
809 return true;
810 }
811
812 // ---------------------------------------------------------------------------
813 // other
814 // ---------------------------------------------------------------------------
815
816 wxWindow *wxMenu::GetWindow() const
817 {
818 if ( m_invokingWindow != NULL )
819 return m_invokingWindow;
820 else if ( GetMenuBar() != NULL)
821 return GetMenuBar()->GetFrame();
822
823 return NULL;
824 }
825
826 // ---------------------------------------------------------------------------
827 // Menu Bar
828 // ---------------------------------------------------------------------------
829
830 void wxMenuBar::Init()
831 {
832 m_eventHandler = this;
833 m_hMenu = 0;
834 #if wxUSE_TOOLBAR && defined(__WXWINCE__)
835 m_toolBar = NULL;
836 #endif
837 // Not using a combined wxToolBar/wxMenuBar? then use
838 // a commandbar in WinCE .NET just to implement the
839 // menubar.
840 #if defined(WINCE_WITH_COMMANDBAR)
841 m_commandBar = NULL;
842 m_adornmentsAdded = false;
843 #endif
844 }
845
846 wxMenuBar::wxMenuBar()
847 {
848 Init();
849 }
850
851 wxMenuBar::wxMenuBar( long WXUNUSED(style) )
852 {
853 Init();
854 }
855
856 wxMenuBar::wxMenuBar(size_t count, wxMenu *menus[], const wxString titles[], long WXUNUSED(style))
857 {
858 Init();
859
860 m_titles.Alloc(count);
861
862 for ( size_t i = 0; i < count; i++ )
863 {
864 m_menus.Append(menus[i]);
865 m_titles.Add(titles[i]);
866
867 menus[i]->Attach(this);
868 }
869 }
870
871 wxMenuBar::~wxMenuBar()
872 {
873 // In Windows CE (not .NET), the menubar is always associated
874 // with a toolbar, which destroys the menu implicitly.
875 #if defined(WINCE_WITHOUT_COMMANDBAR) && defined(__POCKETPC__)
876 if (GetToolBar())
877 {
878 wxToolMenuBar* toolMenuBar = wxDynamicCast(GetToolBar(), wxToolMenuBar);
879 if (toolMenuBar)
880 toolMenuBar->SetMenuBar(NULL);
881 }
882 #else
883 // we should free Windows resources only if Windows doesn't do it for us
884 // which happens if we're attached to a frame
885 if (m_hMenu && !IsAttached())
886 {
887 #if defined(WINCE_WITH_COMMANDBAR)
888 ::DestroyWindow((HWND) m_commandBar);
889 m_commandBar = (WXHWND) NULL;
890 #else
891 ::DestroyMenu((HMENU)m_hMenu);
892 #endif
893 m_hMenu = (WXHMENU)NULL;
894 }
895 #endif
896 }
897
898 // ---------------------------------------------------------------------------
899 // wxMenuBar helpers
900 // ---------------------------------------------------------------------------
901
902 void wxMenuBar::Refresh()
903 {
904 if ( IsFrozen() )
905 return;
906
907 wxCHECK_RET( IsAttached(), wxT("can't refresh unattached menubar") );
908
909 #if defined(WINCE_WITHOUT_COMMANDBAR)
910 if (GetToolBar())
911 {
912 CommandBar_DrawMenuBar((HWND) GetToolBar()->GetHWND(), 0);
913 }
914 #elif defined(WINCE_WITH_COMMANDBAR)
915 if (m_commandBar)
916 DrawMenuBar((HWND) m_commandBar);
917 #else
918 DrawMenuBar(GetHwndOf(GetFrame()));
919 #endif
920 }
921
922 WXHMENU wxMenuBar::Create()
923 {
924 // Note: this doesn't work at all on Smartphone,
925 // since you have to use resources.
926 // We'll have to find another way to add a menu
927 // by changing/adding menu items to an existing menu.
928 #if defined(WINCE_WITHOUT_COMMANDBAR)
929 if ( m_hMenu != 0 )
930 return m_hMenu;
931
932 wxToolMenuBar * const bar = wx_static_cast(wxToolMenuBar *, GetToolBar());
933 if ( !bar )
934 return NULL;
935
936 HWND hCommandBar = GetHwndOf(bar);
937
938 // notify comctl32.dll about the version of the headers we use before using
939 // any other TB_XXX messages
940 SendMessage(hCommandBar, TB_BUTTONSTRUCTSIZE, sizeof(TBBUTTON), 0);
941
942 TBBUTTON tbButton;
943 wxZeroMemory(tbButton);
944 tbButton.iBitmap = I_IMAGENONE;
945 tbButton.fsState = TBSTATE_ENABLED;
946 tbButton.fsStyle = TBSTYLE_DROPDOWN |
947 TBSTYLE_NO_DROPDOWN_ARROW |
948 TBSTYLE_AUTOSIZE;
949
950 for ( unsigned i = 0; i < GetMenuCount(); i++ )
951 {
952 HMENU hPopupMenu = (HMENU) GetMenu(i)->GetHMenu();
953 tbButton.dwData = (DWORD)hPopupMenu;
954 wxString label = wxStripMenuCodes(GetMenuLabel(i));
955 tbButton.iString = (int) label.wx_str();
956
957 tbButton.idCommand = NewControlId();
958 if ( !::SendMessage(hCommandBar, TB_INSERTBUTTON, i, (LPARAM)&tbButton) )
959 {
960 wxLogLastError(wxT("TB_INSERTBUTTON"));
961 }
962 }
963
964 m_hMenu = bar->GetHMenu();
965 return m_hMenu;
966 #else // !__WXWINCE__
967 if ( m_hMenu != 0 )
968 return m_hMenu;
969
970 m_hMenu = (WXHMENU)::CreateMenu();
971
972 if ( !m_hMenu )
973 {
974 wxLogLastError(wxT("CreateMenu"));
975 }
976 else
977 {
978 size_t count = GetMenuCount(), i;
979 wxMenuList::iterator it;
980 for ( i = 0, it = m_menus.begin(); i < count; i++, it++ )
981 {
982 if ( !::AppendMenu((HMENU)m_hMenu, MF_POPUP | MF_STRING,
983 (UINT_PTR)(*it)->GetHMenu(),
984 m_titles[i].wx_str()) )
985 {
986 wxLogLastError(wxT("AppendMenu"));
987 }
988 }
989 }
990
991 return m_hMenu;
992 #endif // __WXWINCE__/!__WXWINCE__
993 }
994
995 int wxMenuBar::MSWPositionForWxMenu(wxMenu *menu, int wxpos)
996 {
997 wxASSERT(menu);
998 wxASSERT(menu->GetHMenu());
999 wxASSERT(m_hMenu);
1000
1001 #if defined(__WXWINCE__)
1002 int totalMSWItems = GetMenuCount();
1003 #else
1004 int totalMSWItems = GetMenuItemCount((HMENU)m_hMenu);
1005 #endif
1006
1007 int i; // For old C++ compatibility
1008 for(i=wxpos; i<totalMSWItems; i++)
1009 {
1010 if(GetSubMenu((HMENU)m_hMenu,i)==(HMENU)menu->GetHMenu())
1011 return i;
1012 }
1013 for(i=0; i<wxpos; i++)
1014 {
1015 if(GetSubMenu((HMENU)m_hMenu,i)==(HMENU)menu->GetHMenu())
1016 return i;
1017 }
1018 wxFAIL;
1019 return -1;
1020 }
1021
1022 // ---------------------------------------------------------------------------
1023 // wxMenuBar functions to work with the top level submenus
1024 // ---------------------------------------------------------------------------
1025
1026 // NB: we don't support owner drawn top level items for now, if we do these
1027 // functions would have to be changed to use wxMenuItem as well
1028
1029 void wxMenuBar::EnableTop(size_t pos, bool enable)
1030 {
1031 wxCHECK_RET( IsAttached(), wxT("doesn't work with unattached menubars") );
1032 wxCHECK_RET( pos < GetMenuCount(), wxT("invalid menu index") );
1033
1034 int flag = enable ? MF_ENABLED : MF_GRAYED;
1035
1036 EnableMenuItem((HMENU)m_hMenu, MSWPositionForWxMenu(GetMenu(pos),pos), MF_BYPOSITION | flag);
1037
1038 Refresh();
1039 }
1040
1041 void wxMenuBar::SetMenuLabel(size_t pos, const wxString& label)
1042 {
1043 wxCHECK_RET( pos < GetMenuCount(), wxT("invalid menu index") );
1044
1045 m_titles[pos] = label;
1046
1047 if ( !IsAttached() )
1048 {
1049 return;
1050 }
1051 //else: have to modify the existing menu
1052
1053 int mswpos = MSWPositionForWxMenu(GetMenu(pos),pos);
1054
1055 UINT_PTR id;
1056 UINT flagsOld = ::GetMenuState((HMENU)m_hMenu, mswpos, MF_BYPOSITION);
1057 if ( flagsOld == 0xFFFFFFFF )
1058 {
1059 wxLogLastError(wxT("GetMenuState"));
1060
1061 return;
1062 }
1063
1064 if ( flagsOld & MF_POPUP )
1065 {
1066 // HIBYTE contains the number of items in the submenu in this case
1067 flagsOld &= 0xff;
1068 id = (UINT_PTR)::GetSubMenu((HMENU)m_hMenu, mswpos);
1069 }
1070 else
1071 {
1072 id = pos;
1073 }
1074
1075 #ifdef __WXWINCE__
1076 MENUITEMINFO info;
1077 wxZeroMemory(info);
1078 info.cbSize = sizeof(info);
1079 info.fMask = MIIM_TYPE;
1080 info.fType = MFT_STRING;
1081 info.cch = label.length();
1082 info.dwTypeData = wx_const_cast(wxChar *, label.wx_str());
1083 if ( !SetMenuItemInfo(GetHmenu(), id, TRUE, &info) )
1084 {
1085 wxLogLastError(wxT("SetMenuItemInfo"));
1086 }
1087
1088 #else
1089 if ( ::ModifyMenu(GetHmenu(), mswpos, MF_BYPOSITION | MF_STRING | flagsOld,
1090 id, label.wx_str()) == (int)0xFFFFFFFF )
1091 {
1092 wxLogLastError(wxT("ModifyMenu"));
1093 }
1094 #endif
1095
1096 Refresh();
1097 }
1098
1099 wxString wxMenuBar::GetMenuLabel(size_t pos) const
1100 {
1101 wxCHECK_MSG( pos < GetMenuCount(), wxEmptyString,
1102 wxT("invalid menu index in wxMenuBar::GetMenuLabel") );
1103
1104 return m_titles[pos];
1105 }
1106
1107 // ---------------------------------------------------------------------------
1108 // wxMenuBar construction
1109 // ---------------------------------------------------------------------------
1110
1111 wxMenu *wxMenuBar::Replace(size_t pos, wxMenu *menu, const wxString& title)
1112 {
1113 wxMenu *menuOld = wxMenuBarBase::Replace(pos, menu, title);
1114 if ( !menuOld )
1115 return NULL;
1116
1117 m_titles[pos] = title;
1118
1119 #if defined(WINCE_WITHOUT_COMMANDBAR)
1120 if (IsAttached())
1121 #else
1122 if (GetHmenu())
1123 #endif
1124 {
1125 int mswpos = MSWPositionForWxMenu(menuOld,pos);
1126
1127 // can't use ModifyMenu() because it deletes the submenu it replaces
1128 if ( !::RemoveMenu(GetHmenu(), (UINT)mswpos, MF_BYPOSITION) )
1129 {
1130 wxLogLastError(wxT("RemoveMenu"));
1131 }
1132
1133 if ( !::InsertMenu(GetHmenu(), (UINT)mswpos,
1134 MF_BYPOSITION | MF_POPUP | MF_STRING,
1135 (UINT_PTR)GetHmenuOf(menu), title.wx_str()) )
1136 {
1137 wxLogLastError(wxT("InsertMenu"));
1138 }
1139
1140 #if wxUSE_ACCEL
1141 if ( menuOld->HasAccels() || menu->HasAccels() )
1142 {
1143 // need to rebuild accell table
1144 RebuildAccelTable();
1145 }
1146 #endif // wxUSE_ACCEL
1147
1148 if (IsAttached())
1149 Refresh();
1150 }
1151
1152 return menuOld;
1153 }
1154
1155 bool wxMenuBar::Insert(size_t pos, wxMenu *menu, const wxString& title)
1156 {
1157 // Find out which MSW item before which we'll be inserting before
1158 // wxMenuBarBase::Insert is called and GetMenu(pos) is the new menu.
1159 // If IsAttached() is false this won't be used anyway
1160 bool isAttached =
1161 #if defined(WINCE_WITHOUT_COMMANDBAR)
1162 IsAttached();
1163 #else
1164 (GetHmenu() != 0);
1165 #endif
1166
1167 int mswpos = (!isAttached || (pos == m_menus.GetCount()))
1168 ? -1 // append the menu
1169 : MSWPositionForWxMenu(GetMenu(pos),pos);
1170
1171 if ( !wxMenuBarBase::Insert(pos, menu, title) )
1172 return false;
1173
1174 m_titles.Insert(title, pos);
1175
1176 if ( isAttached )
1177 {
1178 #if defined(WINCE_WITHOUT_COMMANDBAR)
1179 if (!GetToolBar())
1180 return false;
1181 TBBUTTON tbButton;
1182 memset(&tbButton, 0, sizeof(TBBUTTON));
1183 tbButton.iBitmap = I_IMAGENONE;
1184 tbButton.fsState = TBSTATE_ENABLED;
1185 tbButton.fsStyle = TBSTYLE_DROPDOWN | TBSTYLE_NO_DROPDOWN_ARROW | TBSTYLE_AUTOSIZE;
1186
1187 HMENU hPopupMenu = (HMENU) menu->GetHMenu() ;
1188 tbButton.dwData = (DWORD)hPopupMenu;
1189 wxString label = wxStripMenuCodes(title);
1190 tbButton.iString = (int) label.wx_str();
1191
1192 tbButton.idCommand = NewControlId();
1193 if (!::SendMessage((HWND) GetToolBar()->GetHWND(), TB_INSERTBUTTON, pos, (LPARAM)&tbButton))
1194 {
1195 wxLogLastError(wxT("TB_INSERTBUTTON"));
1196 return false;
1197 }
1198 wxUnusedVar(mswpos);
1199 #else
1200 if ( !::InsertMenu(GetHmenu(), mswpos,
1201 MF_BYPOSITION | MF_POPUP | MF_STRING,
1202 (UINT_PTR)GetHmenuOf(menu), title.wx_str()) )
1203 {
1204 wxLogLastError(wxT("InsertMenu"));
1205 }
1206 #endif
1207 #if wxUSE_ACCEL
1208 if ( menu->HasAccels() )
1209 {
1210 // need to rebuild accell table
1211 RebuildAccelTable();
1212 }
1213 #endif // wxUSE_ACCEL
1214
1215 if (IsAttached())
1216 Refresh();
1217 }
1218
1219 return true;
1220 }
1221
1222 bool wxMenuBar::Append(wxMenu *menu, const wxString& title)
1223 {
1224 WXHMENU submenu = menu ? menu->GetHMenu() : 0;
1225 wxCHECK_MSG( submenu, false, wxT("can't append invalid menu to menubar") );
1226
1227 if ( !wxMenuBarBase::Append(menu, title) )
1228 return false;
1229
1230 m_titles.Add(title);
1231
1232 #if defined(WINCE_WITHOUT_COMMANDBAR)
1233 if (IsAttached())
1234 #else
1235 if (GetHmenu())
1236 #endif
1237 {
1238 #if defined(WINCE_WITHOUT_COMMANDBAR)
1239 if (!GetToolBar())
1240 return false;
1241 TBBUTTON tbButton;
1242 memset(&tbButton, 0, sizeof(TBBUTTON));
1243 tbButton.iBitmap = I_IMAGENONE;
1244 tbButton.fsState = TBSTATE_ENABLED;
1245 tbButton.fsStyle = TBSTYLE_DROPDOWN | TBSTYLE_NO_DROPDOWN_ARROW | TBSTYLE_AUTOSIZE;
1246
1247 size_t pos = GetMenuCount();
1248 HMENU hPopupMenu = (HMENU) menu->GetHMenu() ;
1249 tbButton.dwData = (DWORD)hPopupMenu;
1250 wxString label = wxStripMenuCodes(title);
1251 tbButton.iString = (int) label.wx_str();
1252
1253 tbButton.idCommand = NewControlId();
1254 if (!::SendMessage((HWND) GetToolBar()->GetHWND(), TB_INSERTBUTTON, pos, (LPARAM)&tbButton))
1255 {
1256 wxLogLastError(wxT("TB_INSERTBUTTON"));
1257 return false;
1258 }
1259 #else
1260 if ( !::AppendMenu(GetHmenu(), MF_POPUP | MF_STRING,
1261 (UINT_PTR)submenu, title.wx_str()) )
1262 {
1263 wxLogLastError(wxT("AppendMenu"));
1264 }
1265 #endif
1266
1267 #if wxUSE_ACCEL
1268 if ( menu->HasAccels() )
1269 {
1270 // need to rebuild accelerator table
1271 RebuildAccelTable();
1272 }
1273 #endif // wxUSE_ACCEL
1274
1275 if (IsAttached())
1276 Refresh();
1277 }
1278
1279 return true;
1280 }
1281
1282 wxMenu *wxMenuBar::Remove(size_t pos)
1283 {
1284 wxMenu *menu = wxMenuBarBase::Remove(pos);
1285 if ( !menu )
1286 return NULL;
1287
1288 #if defined(WINCE_WITHOUT_COMMANDBAR)
1289 if (IsAttached())
1290 #else
1291 if (GetHmenu())
1292 #endif
1293 {
1294 #if defined(WINCE_WITHOUT_COMMANDBAR)
1295 if (GetToolBar())
1296 {
1297 if (!::SendMessage((HWND) GetToolBar()->GetHWND(), TB_DELETEBUTTON, (UINT) pos, (LPARAM) 0))
1298 {
1299 wxLogLastError(wxT("TB_DELETEBUTTON"));
1300 }
1301 }
1302 #else
1303 if ( !::RemoveMenu(GetHmenu(), (UINT)MSWPositionForWxMenu(menu,pos), MF_BYPOSITION) )
1304 {
1305 wxLogLastError(wxT("RemoveMenu"));
1306 }
1307 #endif
1308
1309 #if wxUSE_ACCEL
1310 if ( menu->HasAccels() )
1311 {
1312 // need to rebuild accell table
1313 RebuildAccelTable();
1314 }
1315 #endif // wxUSE_ACCEL
1316
1317 if (IsAttached())
1318 Refresh();
1319 }
1320
1321 m_titles.RemoveAt(pos);
1322
1323 return menu;
1324 }
1325
1326 #if wxUSE_ACCEL
1327
1328 void wxMenuBar::RebuildAccelTable()
1329 {
1330 // merge the accelerators of all menus into one accel table
1331 size_t nAccelCount = 0;
1332 size_t i, count = GetMenuCount();
1333 wxMenuList::iterator it;
1334 for ( i = 0, it = m_menus.begin(); i < count; i++, it++ )
1335 {
1336 nAccelCount += (*it)->GetAccelCount();
1337 }
1338
1339 if ( nAccelCount )
1340 {
1341 wxAcceleratorEntry *accelEntries = new wxAcceleratorEntry[nAccelCount];
1342
1343 nAccelCount = 0;
1344 for ( i = 0, it = m_menus.begin(); i < count; i++, it++ )
1345 {
1346 nAccelCount += (*it)->CopyAccels(&accelEntries[nAccelCount]);
1347 }
1348
1349 m_accelTable = wxAcceleratorTable(nAccelCount, accelEntries);
1350
1351 delete [] accelEntries;
1352 }
1353 }
1354
1355 #endif // wxUSE_ACCEL
1356
1357 void wxMenuBar::Attach(wxFrame *frame)
1358 {
1359 wxMenuBarBase::Attach(frame);
1360
1361 #if defined(WINCE_WITH_COMMANDBAR)
1362 if (!m_hMenu)
1363 this->Create();
1364 if (!m_commandBar)
1365 m_commandBar = (WXHWND) CommandBar_Create(wxGetInstance(), (HWND) frame->GetHWND(), NewControlId());
1366 if (m_commandBar)
1367 {
1368 if (m_hMenu)
1369 {
1370 if (!CommandBar_InsertMenubarEx((HWND) m_commandBar, NULL, (LPTSTR) m_hMenu, 0))
1371 {
1372 wxLogLastError(wxT("CommandBar_InsertMenubarEx"));
1373 }
1374 }
1375 }
1376 #endif
1377
1378 #if wxUSE_ACCEL
1379 RebuildAccelTable();
1380 #endif // wxUSE_ACCEL
1381 }
1382
1383 #if defined(WINCE_WITH_COMMANDBAR)
1384 bool wxMenuBar::AddAdornments(long style)
1385 {
1386 if (m_adornmentsAdded || !m_commandBar)
1387 return false;
1388
1389 if (style & wxCLOSE_BOX)
1390 {
1391 if (!CommandBar_AddAdornments((HWND) m_commandBar, 0, 0))
1392 wxLogLastError(wxT("CommandBar_AddAdornments"));
1393 else
1394 return true;
1395 }
1396 return false;
1397 }
1398 #endif
1399
1400 void wxMenuBar::Detach()
1401 {
1402 wxMenuBarBase::Detach();
1403 }
1404
1405 #endif // wxUSE_MENUS