************************************************************************
**       This is my way to thank all of you at CIS for all the        **
**       programming-stuff I learned and ideas I got from you!        **
************************************************************************

If you have any questions or suggestions on this ribbon-program,
just mail me at CIS 100034, 2645

If you plan to alter the ribbon: share it with others! Enjoy!

Hans de Bue

February, 1994
Hoogmade, the Netherlands

This project would not have taken place if it was not triggered by
Shane Holloway (CIS 73443,2457) and his friends, who wrote 
BMPRIBBO.PAS. Thank you!


=========================================================================
== History                                                             ==
=========================================================================

ver  date        description
---  ---------   ------------------------------------------------------
1.1  feb 18 94   - some minor bugfixes
                 - added graying of buttons so that you are able to
                   synchronise the buttonstate with the menu-itemstate
                 - MDI-support added
                 - A number of predefined MS-Windows-style buttons added
                   to the resourcefile RIBBON.RES

1.0  feb 10 94   initial release


========================================================================
== included files                                                     ==
========================================================================

MDI_RIB.PAS     The MDI demonstration program
MDI_RIB.PRF     The preference file for the demonstration
MDI_RIB.RES     It's resource file
MDI_RIB.EXE     Ready to run demo

NCRIBBON.PAS    The demonstration program
NCRIBBON.RES    The accompanying resource file with button images
NCRIBBON.EXE	Ready to run demo

RIBBON.PAS      This is where the actual logic is implemented
RIBBON.RES	A number of pre-defined buttons
RIBBON.TXT	You're reading it now


========================================================================
== Some explanation...                                                ==
========================================================================

The inner workings of the RIBBON may be of interest to you. The principle
is based on using the ChildList (as defined in TWindowsObject) as the
placeholder of all buttons.

The ribbon itself descends from TWindow. When initialized in your main
program, you add buttons and separators as you whish. Just take care
of the order you define them in, because this order is used when
displaying buttons.

When you are ready to display the ribbon, you do so by calling the
ShowButtons method.

That's about it...

TRibbon supports some methods that you may call from your application:

- Init( aParent: PWindowsObject; EditFlag: Boolean );
  Initializes the ribbon. Use EditFlag to state whether or not you want
  your application-users to be able to edit the ribbon or not.

- Resize( Msg: TMessage );
  This method is used in your main application wm_Size handler. Don't
  forget to call it...

- Edit;
  Activates the ribbon-editor if you specified rbn_EnableEdit during
  initialisation. You may call Edit from a menu or just double-click
  the gray area in the ribbon.

- Visible;
  After you've hidden the ribbon, you call Visible to display the ribbon
  again.

- Hide;
  A call to Hide causes the ribbon to hide itself. Call Visible to show.

- AddButton( aBtnID, aCmdID: word;
             aDescription: PChar; InstallFlag: Boolean );
  Adds a button with a button-ID of aBtnID to the ribbon. aCmdID
  corresponds with the ID you specified for the menu-item. This ID will
  be send using wm_Command when you press the button. The description
  is displayed in the ribbon-editor window when you move the cursor
  over the button. InstallFlag specifies whether or not this button
  should be in the ribbon when you start your application.

- AddSeparator;
  Just adds a separator. Using the separator you can easilly group buttons
  in the ribbon.


========================================================================
== Saving the ribbon-state                                            ==
========================================================================

The ribbon is equipped with mechanisms to load and save the state of
the ribbon at any time. You have to take care of that in your application.
Registration of the objects is done in RIBBON.TPW For example:

-----------------------------------------------------------

procedure TDeskTop.LoadPrefs;

var
  OpenFile         : TDosStream;

begin
  OpenFile.Init( PrefsFileName, stOpen );
  OpenFile.Read( ALogFont, SizeOf( ALogFont ));
  OpenFile.Read( PositionFormat, SizeOf( PositionFormat ));
  OpenFile.Read( ToolsDirectory, SizeOf( ToolsDirectory ));
  RibbonBar^.AllButtons := PCollection( OpenFile.Get );
  OpenFile.Done;
end; { TDeskTop.LoadPrefs }

-----------------------------------------------------------

procedure TDeskTop.SavePrefs;

var
  SaveFile         : TDosStream;

begin
  SaveFile.Init( PrefsFileName, stCreate );
  SaveFile.Write( ALogFont, SizeOf( ALogFont ));
  SaveFile.Write( PositionFormat, SizeOf( PositionFormat ));
  SaveFile.Write( ToolsDirectory, SizeOf( ToolsDirectory ));
  SaveFile.Put( RibbonBar^.AllButtons );
  SaveFile.Done;
end; { TDeskTop.SavePrefs }


========================================================================
== Adding buttons                                                     ==
========================================================================

The ribbon is shipped with pre-defined buttons in MicroSoft Windows style.
These buttons are placed in the resourcefile RIBBON.RES:

BtnID   Description
------  ----------------
  201   New
  202   Open
  203   Save
  204   Print
  205   Cut
  206   Copy
  207   Paste
  208   Help
  209   Help with arrow
  210   Sum sign

You can easilly define your own buttons using the Resource Workshop. Just 
create two images: an up-image and a down-image. The up-image is given an
ID of 1xxx and the down-image an ID of 3xxx. XXX stands for the actual
button-ID. For example, the button 'New' with BtnID of 201 will be displayed
using the BMP-images 1201 and 3201. For further information on BMP-buttons
you may read the Borland Pascal books.

When you set up a range of application-specific buttons, it seems wise to
define them in the resource of your application instead of RIBBON.RES. But
that's up to you...


========================================================================
== Some "Limitations"...                                              ==
========================================================================

- use BWCC
- do not use button-ID's already in use by BWCC
- do not use 999 as button-ID: it's in used by the static-control in
  the ribbon editor window

========================================================================
== Demonstration program                                              ==
========================================================================

The demonstration program shows you how you can set up a ribbon bar and
use it within your application.

The principle is simple:
- define a variable of type PRibbon and create it
- create a list of all available buttons [AddButton and AddSeparator]
- show it {ShowRibbon]

Be sure to add the call to ReSize in your wm_Size handler.

