Presenter Screen/How To Add a New UI Control
This page gives an overview of how to write and add a new UI Control.
The examples will focus on progress bar that displays the current position in the document, i.e. instead of (or maybe additionally to) saying 5 / 10 when you are on slide 5 in a document with 10 slides a half full progress bar is painted. Translating this to other kinds of controls should be fairly easy.
This page describes the most simple and straight forward way to do that. With a working copy of the presenterview child work space you should be able to create a new progress bar in one afternoon.
For a new UI control that is displayed on the presenter screen you have to do two things:
- Provide its implementation. This will typically be a view that implements the com::sun::star::drawing::framework::XView interface and that paints its output on a com::sun::star::rendering::XCanvas object. The view is created by a factory object, for instance the PresenterViewFactory class in the sdext module.
- Define where and how to display it. You can adapt the Impress.xcu file to define a new layout or modify an existing layout. In the Impress.xcu file you can define
- that the view is displayed at all
- its relative coordinates
- the style of its border, i.e. title or no title, border or no border.
Implementation of a new View
Start with the PresenterSlidePreview class in sdext/source/presenter. This is a very simple control. You basically just have to replace its SetSlide() and Paint() methods. Lets assume that you call your new class PresenterProgressBar.
The SetSlide() method is called whenever the slide show jumps to another slide. For the progress bar you need two pieces of information, the number of the current slide and the total number of slides int he presentation. Have a look at the PresenterToolBar class to see how this can be done. Look at UpdateSlideNumber() for the total number of slides and at SetCurrentSlide() for the number of the current slide. Store both numbers and request a repaint by calling the com::sun::star::awt::XWindowPeer::invalidate() method (called at the end of PresenterSlidePreview::SetSlide()).
Invalidating the window of the control will result eventually in a call to Paint(). Use the mxCanvas member of your new PresenterProgressBar class for painting a progress bar. Have a look at the current implementation of the Paint() method to get an impression of how to use the canvas. Use your imagination for how the progress bar shall look.
Register the new View
Now that you have the implementation of the new progress bar it has to be made available to the drawing framework so that it can be used by the presenter screen. Add the new view to the PresenterViewFactory. In a nutshell, see where the slide preview is mentioned and add the progress bar accordingly. In slightly more detail:
- Add a URL that acts as identifier of the progress bar, like msNextSlidePreviewViewURL.
- Register the new view at the configuration controller. Look at the Register() method for how this is done.
- Add code for the actual creation of the progress bar view to the createResource() method.
Register a new Pane
For the new view you need a new pane as well. [This will hopefully change in the near future, so that new panes are created on demand] This is even simpler than creating the view. Change the PresenterPaneFactory class by adding a new pane just like the msNextSlidePreviewPaneURL.
- Add a URL for the new pane.
- Register it in the Register() method.
- Creation is done automatically, no change neccessary.
Display the new Control
What remains to be done is to add the progress bar to the Impress.xcu file so that it is displayed. Again, look at how this is done for the slide preview (for the next slide) add the progress bar accordingly:
- There is an array "StyleAssociations" where a display style is defined for every view and pane. Styles define colors, fonts, borders. Look for "NextSlidePreviewPane" and "NextSlidePreviewView" and add entries for e.g. "ProgressBarPane" and "ProgressBarView".
- The "DefaultLayout" entry in the "Layouts" array defines where to place a pane. Positions and sizes are given in relative values. Left or a zero
width is denoted by 0, right or a width like the window width is represented by 1. Add an entry like "NextSlidePreview" for the progress bar and change the URLs of both view and pane to use and change the title, possibly to the empty string to avoid the display of a window title. Adapt the relative position and size to place the progress bar where you want it to be. You probably have to change the position and sizes of other controls to make room for the progress bar.
Rebuild the presenter screen extension and re-install it.
Start the office, start the presentation and your new progress bar should be visible.