Follow

Adding a Position Indicator

We've now added some functionality to the Pugpig framework to make it easier for you to add a position indicator to your UI. Basically you need to add a UIPageControl somewhere in your interface, and then link that up to the Pugpig paged doc control.

Adding a UIPageControl

If you're not familiar with adding controls to your interface, this is what you'd need to do:

In the DocumentViewController.h file, you should add an outlet for the UIPageControl. It doesn't matter too much where you put it, but a good place would be under the other outlet properties.
@property (nonatomic, retain) IBOutlet UIPageControl *positionIndicator;

In the DocumentViewController.m file, you'll need to add a line to synthesize this new property, near the top of the file where all the other properties are synthesized. Again, it doesn't matter too much where exactly you add the line, but it's good practice too keep the properties here in the same order they are declared in the .h file.
@synthesize positionIndicator;
Also in DocumentViewController.m, in the dealloc method, you'll need to add a line to release the property. Again, best to add the line in the same position relative to the other properties that you've used in steps one and two.
[positionIndicator release];
Finally, in the viewDidUnload method, add a line setting the property to nil. Again, the same position relative to the other properties as in the previous steps.
self.positionIndicator = nil;

In 
DocumentView-iPad.xib you'll need to add a Page Control object onto your interface somewhere. Where exactly you put it will depend on the design of your user interface. One typical position is at the very bottom of the screen (Y offset of 968 if you're using the portrait layout and have the status bar enabled). The width is best set to the full width of the device (768 in portrait with an X offset of 0). The height is hardcoded at 36. You can set these positions on the Size Inspector tab of the Utilities view.

You should now also set the autosizing options so that the control will reposition itself correctly when the device is rotated. If you're positioning the control at the bottom of the screen as suggested in step 5, make sure that the width sizing spring is enabled, and all the edge struts are enabled except for the top strut. This will keep the control expanded to fit the width of the device and aligned with the bottom edge.

As far as the z order is concerned, you'll probably want the control to be above the pugpig
 Paged Doc Control, but below popup windows like the Search Control (if you're using that) and possibly also below the Thumbnail Control (unless you also want it to be visible when the thumbnail control is visible). The z order is determined by the position of the object in the Objects tree on the left of the screen. Lower down the list is higher up in the z order.

Finally we need to link up this control with the property we created earlier. You do this via the
 Connection Inspector tab of the Utilitiesview. Click on the little dot next to New Referencing Outlet and, while keeping the mouse button held down, drag the line from the referencing outlet onto the File's Owner entry in the Placeholders list on the left of the screen. When you let go of the mouse button you should get a popup menu listing the outlet properties that you can connect with - the one you want is positionIndicator (the property you created in step one).

If you're creating a universal app, you'll need to repeat steps five to eight for the iPhone version of the interface, in
 DocumentView-iPhone.xib. Again, the positioning of the control is up to you, but if you choose to put it at the bottom of the screen, the Y offset would be 424 (again assuming a portrait layout with the status bar enabled), the X offset 0, the width would be 320, and the height hardcoded at 36.Integrating with Pugpig

Now comes the bit where you hook up the control you've just created to the paged doc control. This is essentially just one line of code which you add to the viewDidLoad method in the DocumentViewController.m file.

[pageControl setPositionIndicator:positionIndicator];

A good place to add this is where all the other properties on the pageControl object are set, preferably before any of the others.

By default, pugpig will update your UIPageControl with an indication of which page is currently being viewed, but if you're using theKGVariablePanePartitioning class for your paneManager, you could also choose to show which pane is being viewed, either relative to the current page, or relative to the total pane count in the document (only really practical for short documents).

You do this by setting the 

[pageControl setPositionIndicatorStyle:KGPositionIndicatorShowsPanesPerPage];
positionIndicatorStyle property.

 

It's best to call setPositionIndicatorStyle before calling setPositionIndicator. Supported styles are:

  • KGPositionIndicatorShowsPages (the default)
  • KGPositionIndicatorShowsPanes
  • KGPositionIndicatorShowsPanesPerPage

Note that the second option (KGPositionIndicatorShowsPanes), is not recommended with the current version of pugpig, because of the way panes are calculated.

The number of panes making up a document has to be calculated on the fly, and that information isn't currently cached. As a result, you'll see the total number of panes constantly changing as you move from page to page, and the framework figures out how many panes there are in each page. This issue should be addressed in a future version of the framework.

Light Background Colours

One of the things you should be aware of when using the standard iOS UIPageControl is that it doesn't work particularly well on top of a light background colour (on white it's essentially invisible). If the view behind the page control is light in colour, you may need to add an additional view in your interface with a dark background colour and position that behind the page control.

Note that you can't just change the background colour on the page control itself because there are times when it hides itself, and if the view behind it is a different colour, you'll see that section of the screen flashing between the two colours as it appears and disappears.

An alternative solution would be to implement your own custom version of a UIPageControl that works better with light background colours, but that is beyond the scope of this document.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk