fdo#74697 Add Bluez 5 support for impress remote.
[LibreOffice.git] / include / sfx2 / itemconnect.hxx
blob95a545e3dad44d4a0928cbd3d97d35ab2ba8f94e
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /*
3 * This file is part of the LibreOffice project.
5 * This Source Code Form is subject to the terms of the Mozilla Public
6 * License, v. 2.0. If a copy of the MPL was not distributed with this
7 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
9 * This file incorporates work covered by the following license notice:
11 * Licensed to the Apache Software Foundation (ASF) under one or more
12 * contributor license agreements. See the NOTICE file distributed
13 * with this work for additional information regarding copyright
14 * ownership. The ASF licenses this file to you under the Apache
15 * License, Version 2.0 (the "License"); you may not use this file
16 * except in compliance with the License. You may obtain a copy of
17 * the License at http://www.apache.org/licenses/LICENSE-2.0 .
20 #ifndef SFX_ITEMCONNECT_HXX
21 #define SFX_ITEMCONNECT_HXX
23 #include "sal/config.h"
24 #include "sfx2/dllapi.h"
26 #include <memory>
27 #include <sfx2/itemwrapper.hxx>
28 #include <sfx2/controlwrapper.hxx>
30 // ============================================================================
32 namespace sfx {
34 // ============================================================================
36 typedef int ItemConnFlags;
38 /** No special state for the connection. */
39 const ItemConnFlags ITEMCONN_NONE = 0x0000;
41 /** Connection is inactive - virtual functions will not be called. */
42 const ItemConnFlags ITEMCONN_INACTIVE = 0x0001;
44 /** Enable control(s), if the item is known. */
45 const ItemConnFlags ITEMCONN_ENABLE_KNOWN = 0x0010;
46 /** Disable control(s), if the item is unknown. */
47 const ItemConnFlags ITEMCONN_DISABLE_UNKNOWN = 0x0020;
48 /** Show control(s), if the item is known. */
49 const ItemConnFlags ITEMCONN_SHOW_KNOWN = 0x0040;
50 /** Hide control(s), if the item is unknown. */
51 const ItemConnFlags ITEMCONN_HIDE_UNKNOWN = 0x0080;
53 /** Default value for constructors. */
54 const ItemConnFlags ITEMCONN_DEFAULT = ITEMCONN_NONE;
56 // ============================================================================
57 // Base connection classes
58 // ============================================================================
60 /** A helper for SfxTabPages to connect controls to items.
62 This is the base class of all control connection classes. Their purpose is
63 to connect one or more controls from an SfxTabPage with an item from an
64 item set. The goal is to omit any additional code in the virtual functions
65 Reset() and FillItemSet() in classes derived from SfxTabPage.
67 Examples of connections:
68 - A check box with an SfxBoolItem,
69 - A metric (spin) field with an SfxInt32Item.
70 - A group of radio buttons with an SfxEnumItem.
72 Each SfxTabPage will contain a list of connection objects (derived from
73 this class). The connection objects remember the item and control(s) they
74 have to work on. The SfxTabPage will call the DoApplyFlags(), DoReset(),
75 and DoFillItemSet() functions of all connection objects it knows. The code
76 to initialize control(s) from the item value and fill the item from
77 control(s) has to be written only once for each control type.
79 Additional flags passed in the constructor allow to control the behaviour
80 of the control(s) if the item is supported/unsupported in the currently
81 used item set. For example, it is possible to specify that a control will
82 be disabled or hidden if the item is not supported. This is done before
83 each call of Reset().
85 The special flag ITEMCONN_CLONE_ITEM controls how to create new items in
86 the DoFillItemSet() function. The standard (and faster) method is to create
87 a temporary item on the stack and put it into the item set. But this does
88 not work if the item set expects a special item type derived from a common
89 item class, i.e. a Boolean item derived from SfxBoolItem providing special
90 item representation text. As this code does not know the item type, the
91 item cannot be created on the stack. For this case the flag specifies to
92 use the virtual Clone() method of the pool default item. This will create
93 an item of the correct type but can still be used in conjunction with i.e.
94 the standard BoolItemWrapper.
96 How to use the item connection feature:
98 A) Single item <-> single control connection
100 Example: An SfxBoolItem and a check box.
102 A1) Create a new item wrapper class derived from the SingleItemWrapper
103 template, or use the template directly, or use one of the
104 predefined item wrappers. See documentation of the
105 SingleItemWrapper template for details (itemwrapper.hxx).
106 A2) Create a new control wrapper class derived from the
107 SingleControlWrapper template and implement the abstract functions,
108 or use one of the predefined control wrappers. See documentation of
109 the SingleControlWrapper template for details (controlwrapper.hxx).
110 A3) Create a new connection class derived from one of the following
111 base classes, and implement the abstract functions, or use the
112 ItemControlConnection template directly, or use one of the
113 predefined connections.
114 A4) Create connection objects in the constructor of the tab page, and
115 insert them into the tab page with SfxTabPage::AddItemConnection().
116 A5) Remove old code from the tab page's Reset() and FillItemSet()
117 functions, if necessary.
119 B) Single item <-> multiple controls connections
121 B1) See step A1. If the item contains multiple values (and not a
122 structure that contains all the values for the different controls),
123 the best way is to use the IdentItemWrapper template, that works
124 with the item itself. This way it is possible to provide a 'data
125 type' that contains the values for all controls.
126 B2) Create a new control wrapper class derived from the
127 MultiControlWrapper template. Add single control wrapper members
128 for all controls to this class and register them in the
129 constructor, using the RegisterControlWrapper() function. Implement
130 the abstract functions GetControlValue() and SetControlValue().
131 These functions should call the respective functions of the own
132 single control wrappers and either fill a new data object (the item
133 itself in most cases, see step B1) with all the values from the
134 controls, or fill all the controls from the data object.
135 B3) Create a new connection class derived from ItemControlConnection,
136 or use the ItemControlConnection template directly. The multiple
137 control wrapper from step B2 acts like a single control, therefore
138 it is possible to use the ItemControlConnection.
139 B4) See steps A4 and A5.
141 C) Multiple items <-> single control connections
143 todo
145 D) Multiple items <-> multiple controls connections
147 todo
149 The current tree of base classes/templates and standard connections:
151 ItemConnectionBase
153 +- DummyItemConnection [1]
155 +- ItemControlConnection< ItemWrpT, ControlWrpT >
157 | +- CheckBoxConnection [1]
159 | +- NumericConnection< ItemWrpT > [1]
160 | | |
161 | | +- [ValueType]NumericConnection [1] [2]
163 | +- MetricConnection< ItemWrpT > [1]
164 | | |
165 | | +- [ValueType]MetricConnection [1] [2]
167 | +- ListBoxConnection< ItemWrpT > [1]
168 | | |
169 | | +- [ValueType]ListBoxConnection [1] [2]
171 | +- ValueSetConnection< ItemWrpT > [1]
173 | +- [ValueType]ValueSetConnection [1] [2]
175 +- ItemConnectionArray [1]
177 Notes:
178 [1] Standard connections ready to use.
179 [2] [ValueType] is one of Int16, UInt16, Int32, UInt32.
181 class SFX2_DLLPUBLIC ItemConnectionBase
183 public:
184 virtual ~ItemConnectionBase();
186 /** Returns the flags passed in the constructor. */
187 inline ItemConnFlags GetFlags() const { return mnFlags; }
189 /** Returns true if this connection is active. */
190 bool IsActive() const;
192 /** Calls the virtual ApplyFlags() function, if connection is active. */
193 void DoApplyFlags( const SfxItemSet& rItemSet );
194 /** Calls the virtual Reset() function, if connection is active. */
195 void DoReset( const SfxItemSet& rItemSet );
196 /** Calls the virtual FillItemSet() function, if connection is active. */
197 bool DoFillItemSet( SfxItemSet& rDestSet, const SfxItemSet& rOldSet );
199 protected:
200 explicit ItemConnectionBase( ItemConnFlags nFlags = ITEMCONN_DEFAULT );
202 /** Derived classes implement actions according to current flags here. */
203 virtual void ApplyFlags( const SfxItemSet& rItemSet ) = 0;
204 /** Derived classes implement initializing controls from item sets here. */
205 virtual void Reset( const SfxItemSet& rItemSet ) = 0;
206 /** Derived classes implement filling item sets from controls here. */
207 virtual bool FillItemSet( SfxItemSet& rDestSet, const SfxItemSet& rOldSet ) = 0;
209 /** Returns whether to enable a control, according to current flags. */
210 TriState GetEnableState( bool bKnown ) const;
211 /** Returns whether to show a control, according to current flags. */
212 TriState GetShowState( bool bKnown ) const;
214 private:
215 /* Disable copy c'tor and assignment. */
216 ItemConnectionBase( const ItemConnectionBase& );
217 ItemConnectionBase& operator=( const ItemConnectionBase& );
219 ItemConnFlags mnFlags; /// Flags for additional options.
222 // ----------------------------------------------------------------------------
224 /** Base class template for single item <-> single control connection objects.
226 This template uses functions provided by the SingleItemWrapper and the
227 SingleControlWrapper template classes. The virtual functions ApplyFlags(),
228 Reset(), and FillItemSet() are implemented here in a generic way using the
229 virtual functions of the wrapper classes. Derived classes only have to
230 create or otherwise provide appropriate wrappers.
232 template< typename ItemWrpT, typename ControlWrpT >
233 class ItemControlConnection : public ItemConnectionBase
235 public:
236 typedef ItemWrpT ItemWrapperType;
237 typedef ControlWrpT ControlWrapperType;
238 typedef ItemControlConnection< ItemWrpT, ControlWrpT > ItemControlConnectionType;
239 typedef typename ItemWrpT::ItemType ItemType;
240 typedef typename ItemWrpT::ItemValueType ItemValueType;
241 typedef typename ControlWrpT::ControlType ControlType;
242 typedef typename ControlWrpT::ControlValueType ControlValueType;
244 typedef std::auto_ptr< ItemWrpT > ItemWrapperRef;
245 typedef std::auto_ptr< ControlWrpT > ControlWrapperRef;
247 /** Receives pointer to a newly created control wrapper.
248 @descr Takes ownership of the control wrapper. */
249 explicit ItemControlConnection( sal_uInt16 nSlot, ControlWrpT* pNewCtrlWrp,
250 ItemConnFlags nFlags = ITEMCONN_DEFAULT );
252 /** Convenience constructor. Receives reference to a control directly.
253 @descr May only be used, if ControlWrpT::ControlWrpT( ControlType& )
254 constructor exists. */
255 explicit ItemControlConnection( sal_uInt16 nSlot, ControlType& rControl,
256 ItemConnFlags nFlags = ITEMCONN_DEFAULT );
258 virtual ~ItemControlConnection();
260 protected:
261 /** Actions according to current flags for the control. */
262 virtual void ApplyFlags( const SfxItemSet& rItemSet );
263 /** Resets the control according to the item contents. */
264 virtual void Reset( const SfxItemSet& rItemSet );
265 /** Fills the item set according to the control's state. */
266 virtual bool FillItemSet( SfxItemSet& rDestSet, const SfxItemSet& rOldSet );
268 ItemWrapperType maItemWrp;
269 ControlWrapperRef mxCtrlWrp;
272 // ============================================================================
273 // Standard connections
274 // ============================================================================
276 /** This is a helper class to enable/disable/show/hide a control only.
278 This class does nothing special in the Reset() and FillItemSet() functions.
279 It can be used to control the visibility of i.e. fixed lines or fixed texts
280 related to the availability of an item by passing the appropriate flags to
281 the constructor of this connection.
283 class SFX2_DLLPUBLIC DummyItemConnection:
284 public ItemConnectionBase, public DummyWindowWrapper
286 public:
287 explicit DummyItemConnection( sal_uInt16 nSlot, Window& rWindow,
288 ItemConnFlags nFlags = ITEMCONN_DEFAULT );
290 protected:
291 virtual void ApplyFlags( const SfxItemSet& rItemSet );
292 virtual void Reset( const SfxItemSet& rItemSet );
293 virtual bool FillItemSet( SfxItemSet& rDestSet, const SfxItemSet& rOldSet );
295 private:
296 sal_uInt16 mnSlot;
299 // ----------------------------------------------------------------------------
301 /** Connection between an SfxBoolItem and a VCL CheckBox. */
302 typedef ItemControlConnection< BoolItemWrapper, CheckBoxWrapper > CheckBoxConnection;
304 // ============================================================================
306 /** Connection between an item and the VCL NumericField. */
307 template< typename ItemWrpT >
308 class NumericConnection : public ItemControlConnection< ItemWrpT,
309 NumericFieldWrapper< typename ItemWrpT::ItemValueType > >
311 typedef ItemControlConnection< ItemWrpT,
312 NumericFieldWrapper< typename ItemWrpT::ItemValueType > >
313 ItemControlConnectionType;
315 public:
316 typedef typename ItemControlConnectionType::ControlWrapperType NumericFieldWrapperType;
318 explicit NumericConnection( sal_uInt16 nSlot, NumericField& rField,
319 ItemConnFlags nFlags = ITEMCONN_DEFAULT );
322 // ----------------------------------------------------------------------------
324 typedef NumericConnection< Int16ItemWrapper > Int16NumericConnection;
325 typedef NumericConnection< UInt16ItemWrapper > UInt16NumericConnection;
326 typedef NumericConnection< Int32ItemWrapper > Int32NumericConnection;
327 typedef NumericConnection< UInt32ItemWrapper > UInt32NumericConnection;
329 // ============================================================================
331 /** Connection between an item and the VCL MetricField.
333 Adds support of different field units during control value <-> item value
334 conversion. The field unit passed to the constructor applies for the item
335 values, while the field unit used in the control has to be set at the
336 control itself.
338 template< typename ItemWrpT >
339 class MetricConnection : public ItemControlConnection< ItemWrpT,
340 MetricFieldWrapper< typename ItemWrpT::ItemValueType > >
342 typedef ItemControlConnection< ItemWrpT,
343 MetricFieldWrapper< typename ItemWrpT::ItemValueType > >
344 ItemControlConnectionType;
346 public:
347 typedef typename ItemControlConnectionType::ControlWrapperType MetricFieldWrapperType;
349 explicit MetricConnection( sal_uInt16 nSlot, MetricField& rField,
350 FieldUnit eItemUnit = FUNIT_NONE, ItemConnFlags nFlags = ITEMCONN_DEFAULT );
353 // ----------------------------------------------------------------------------
355 typedef MetricConnection< Int16ItemWrapper > Int16MetricConnection;
356 typedef MetricConnection< UInt16ItemWrapper > UInt16MetricConnection;
357 typedef MetricConnection< Int32ItemWrapper > Int32MetricConnection;
358 typedef MetricConnection< UInt32ItemWrapper > UInt32MetricConnection;
360 // ============================================================================
362 /** Connection between an item and a VCL ListBox.
364 Optionally a map can be passed that maps list box positions to item values.
365 This map MUST be terminated with an entry containing LISTBOX_ENTRY_NOTFOUND
366 as list box position. The item value contained in this last entry is used
367 as default item value in case of an error.
369 template< typename ItemWrpT >
370 class ListBoxConnection : public ItemControlConnection< ItemWrpT,
371 ListBoxWrapper< typename ItemWrpT::ItemValueType > >
373 typedef ItemControlConnection< ItemWrpT,
374 ListBoxWrapper< typename ItemWrpT::ItemValueType > >
375 ItemControlConnectionType;
377 public:
378 typedef typename ItemControlConnectionType::ControlWrapperType ListBoxWrapperType;
379 typedef typename ListBoxWrapperType::MapEntryType MapEntryType;
381 explicit ListBoxConnection( sal_uInt16 nSlot, ListBox& rListBox,
382 const MapEntryType* pMap = 0, ItemConnFlags nFlags = ITEMCONN_DEFAULT );
385 // ----------------------------------------------------------------------------
387 typedef ListBoxConnection< Int16ItemWrapper > Int16ListBoxConnection;
388 typedef ListBoxConnection< UInt16ItemWrapper > UInt16ListBoxConnection;
389 typedef ListBoxConnection< Int32ItemWrapper > Int32ListBoxConnection;
390 typedef ListBoxConnection< UInt32ItemWrapper > UInt32ListBoxConnection;
392 // ============================================================================
394 /** Connection between an item and an SVTOOLS ValueSet.
396 Optionally a map can be passed that maps value set identifiers to item
397 values. This map MUST be terminated with an entry containing
398 VALUESET_ITEM_NOTFOUND as value set identifier. The item value contained in
399 this last entry is used as default item value in case of an error.
401 template< typename ItemWrpT >
402 class ValueSetConnection : public ItemControlConnection< ItemWrpT,
403 ValueSetWrapper< typename ItemWrpT::ItemValueType > >
405 typedef ItemControlConnection< ItemWrpT,
406 ValueSetWrapper< typename ItemWrpT::ItemValueType > >
407 ItemControlConnectionType;
409 public:
410 typedef typename ItemControlConnectionType::ControlWrapperType ValueSetWrapperType;
411 typedef typename ValueSetWrapperType::MapEntryType MapEntryType;
413 explicit ValueSetConnection( sal_uInt16 nSlot, ValueSet& rValueSet,
414 const MapEntryType* pMap = 0, ItemConnFlags nFlags = ITEMCONN_DEFAULT );
417 // ----------------------------------------------------------------------------
419 typedef ValueSetConnection< Int16ItemWrapper > Int16ValueSetConnection;
420 typedef ValueSetConnection< UInt16ItemWrapper > UInt16ValueSetConnection;
421 typedef ValueSetConnection< Int32ItemWrapper > Int32ValueSetConnection;
422 typedef ValueSetConnection< UInt32ItemWrapper > UInt32ValueSetConnection;
424 // ============================================================================
425 // Array of connections
426 // ============================================================================
428 class ItemConnectionArrayImpl;
430 /** A container of connection objects.
432 This is a connection with the only purpose to contain other connection
433 objects. This way it is possible to create a tree structure of connections
434 for a convenient connection management. This class is used by the class
435 SfxTabPage to store all connections.
437 class ItemConnectionArray : public ItemConnectionBase
439 public:
440 explicit ItemConnectionArray();
441 virtual ~ItemConnectionArray();
443 /** Adds a new connection to the list.
444 @descr Takes ownership of the connection! */
445 void AddConnection( ItemConnectionBase* pConnection );
447 protected:
448 virtual void ApplyFlags( const SfxItemSet& rItemSet );
449 virtual void Reset( const SfxItemSet& rItemSet );
450 virtual bool FillItemSet( SfxItemSet& rDestSet, const SfxItemSet& rOldSet );
452 private:
453 std::auto_ptr< ItemConnectionArrayImpl > mxImpl;
456 // ============================================================================
458 // ============================================================================
459 // *** Implementation of template functions ***
460 // ============================================================================
462 // ============================================================================
463 // Base connection classes
464 // ============================================================================
466 template< typename ItemWrpT, typename ControlWrpT >
467 ItemControlConnection< ItemWrpT, ControlWrpT >::ItemControlConnection(
468 sal_uInt16 nSlot, ControlWrpT* pNewCtrlWrp, ItemConnFlags nFlags ) :
469 ItemConnectionBase( nFlags ),
470 maItemWrp( nSlot ),
471 mxCtrlWrp( pNewCtrlWrp )
475 template< typename ItemWrpT, typename ControlWrpT >
476 ItemControlConnection< ItemWrpT, ControlWrpT >::ItemControlConnection(
477 sal_uInt16 nSlot, ControlType& rControl, ItemConnFlags nFlags ) :
478 ItemConnectionBase( nFlags ),
479 maItemWrp( nSlot ),
480 mxCtrlWrp( new ControlWrpT( rControl ) )
484 template< typename ItemWrpT, typename ControlWrpT >
485 ItemControlConnection< ItemWrpT, ControlWrpT >::~ItemControlConnection()
489 template< typename ItemWrpT, typename ControlWrpT >
490 void ItemControlConnection< ItemWrpT, ControlWrpT >::ApplyFlags( const SfxItemSet& rItemSet )
492 bool bKnown = ItemWrapperHelper::IsKnownItem( rItemSet, maItemWrp.GetSlotId() );
493 mxCtrlWrp->ModifyControl( GetEnableState( bKnown ), GetShowState( bKnown ) );
496 template< typename ItemWrpT, typename ControlWrpT >
497 void ItemControlConnection< ItemWrpT, ControlWrpT >::Reset( const SfxItemSet& rItemSet )
499 const ItemType* pItem = maItemWrp.GetUniqueItem( rItemSet );
500 mxCtrlWrp->SetControlDontKnow( pItem == 0 );
501 if( pItem )
502 mxCtrlWrp->SetControlValue( maItemWrp.GetItemValue( *pItem ) );
505 template< typename ItemWrpT, typename ControlWrpT >
506 bool ItemControlConnection< ItemWrpT, ControlWrpT >::FillItemSet(
507 SfxItemSet& rDestSet, const SfxItemSet& rOldSet )
509 const ItemType* pOldItem = maItemWrp.GetUniqueItem( rOldSet );
510 bool bChanged = false;
511 if( !mxCtrlWrp->IsControlDontKnow() )
513 // first store the control value in a local variable
514 ControlValueType aCtrlValue( mxCtrlWrp->GetControlValue() );
515 // convert to item value type -> possible to convert i.e. from 'T' to 'const T&'
516 ItemValueType aNewValue( aCtrlValue );
517 // do not rely on existence of ItemValueType::operator!=
518 if( !pOldItem || !(maItemWrp.GetItemValue( *pOldItem ) == aNewValue) )
520 sal_uInt16 nWhich = ItemWrapperHelper::GetWhichId( rDestSet, maItemWrp.GetSlotId() );
521 std::auto_ptr< ItemType > xItem(
522 static_cast< ItemType* >( maItemWrp.GetDefaultItem( rDestSet ).Clone() ) );
523 xItem->SetWhich( nWhich );
524 maItemWrp.SetItemValue( *xItem, aNewValue );
525 rDestSet.Put( *xItem );
526 bChanged = true;
529 if( !bChanged )
530 ItemWrapperHelper::RemoveDefaultItem( rDestSet, rOldSet, maItemWrp.GetSlotId() );
531 return bChanged;
534 // ============================================================================
535 // Standard connections
536 // ============================================================================
538 template< typename ItemWrpT >
539 NumericConnection< ItemWrpT >::NumericConnection(
540 sal_uInt16 nSlot, NumericField& rField, ItemConnFlags nFlags ) :
541 ItemControlConnectionType( nSlot, rField, nFlags )
545 // ============================================================================
547 template< typename ItemWrpT >
548 MetricConnection< ItemWrpT >::MetricConnection(
549 sal_uInt16 nSlot, MetricField& rField, FieldUnit eItemUnit, ItemConnFlags nFlags ) :
550 ItemControlConnectionType( nSlot, new MetricFieldWrapperType( rField, eItemUnit ), nFlags )
554 // ============================================================================
556 template< typename ItemWrpT >
557 ListBoxConnection< ItemWrpT >::ListBoxConnection(
558 sal_uInt16 nSlot, ListBox& rListBox, const MapEntryType* pMap, ItemConnFlags nFlags ) :
559 ItemControlConnectionType( nSlot, new ListBoxWrapperType( rListBox, pMap ), nFlags )
563 // ============================================================================
565 template< typename ItemWrpT >
566 ValueSetConnection< ItemWrpT >::ValueSetConnection(
567 sal_uInt16 nSlot, ValueSet& rValueSet, const MapEntryType* pMap, ItemConnFlags nFlags ) :
568 ItemControlConnectionType( nSlot, new ValueSetWrapperType( rValueSet, pMap ), nFlags )
572 // ============================================================================
574 } // namespace sfx
576 #endif
578 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */