Customising the Document Picker

Static Customisation

Each document displayed in the document picker is represented by four controls:

UIView KGDocumentPickerCover
UIProgressView KGDocumentPickerProgressBar
UILabel KGDocumentPickerLabel
UIButton KGDocumentPickerDownloadButton

Of these, the label and download button are optional, and can be enabled or disabled via properties in the KGDocumentPicker object:

@property setShouldShowDownloadButton
@property setShouldShowDocumentName

By default, the Xcode template sets both properties to YES in the viewDidLoad method of the DocumentPickerViewController class. If you want to hide either of those controls, just set the appropriate property to NO.

If you want to change the styling of any of these controls, you can do so by overriding the documentPicker:didAddControlsForDocument:inView: delegate method. You can obtain a reference to the various controls by calling viewWithTag: on the provided view and specifing the appropriate tag constant from the table above. For example, to set the button background colour to red, you might do something like this:

- (void)documentPicker:(KGDocumentPicker*)picker didAddControlsForDocument:(KGDocument*)document inView:(UIView*)view {
  UIButton *button = (UIButton*)[view viewWithTag:KGDocumentPickerDownloadButton];
  [button setBackgroundColor:[UIColor redColor]];

You could just as easily, tweak the position and size of these controls, or even add additional controls of your own.

Dynamic Customisation

In addition to the static customisation explained above, it's also possible to modify the display of items in the document picker as the user navigates through the list. For example, the default Xcode template implementation uses this functionality to adjust the alpha level of items so that the focused item is completely opaque, while items further from the centre become more and more transparent.

This customisation is achieved by overriding the documentPicker:willRenderDocument:inView:atOffset: delegate method. This works essentially the same way as the didAddControlsForDocument method, except it has an additional offset parameter which represents the item's distance from the centre point. This offset value is normalised and capped in the range 0 to 1 (0 being the centremost value).

For the example, if you wanted to scale the items in the document picker so the further an item is from the centre the smaller it will be, your code might look something like this:

- (void)documentPicker:(KGDocumentPicker*)picker willRenderDocument:(KGDocument*)document inView:(UIView*)view atOffset:(CGFloat)offset {
  CGFloat scale = 1.0-offset/4;
  [view setTransform:CGAffineTransformMakeScale(scale, scale)];

In addition, you would need to set the default value (in this example, a scale of 0.75) in the didAddControlsForDocument method.

- (void)documentPicker:(KGDocumentPicker*)picker didAddControlsForDocument:(KGDocument*)document inView:(UIView*)view {
  CGFloat scale = 0.75;
  [view setTransform:CGAffineTransformMakeScale(scale, scale)];

Synchronising Secondary Details

Another use for the willRenderDocument method is when you want to display secondary details about the currently focused item. For example, if you had a description field which you wanted to populate with the description of the currently focused document, you could do something like this:

- (void)documentPicker:(KGDocumentPicker*)picker willRenderDocument:(KGDocument*)document inView:(UIView*)view atOffset:(CGFloat)offset {
  if (offset < 0.5) {
    // assuming the existence of a UITextView field named description
    [description setText:[document description]];

We test for an offset less than 0.5 because that's the point at which the item moves closer to centre than the previously centred item.

Adding a custom background image for each orientation

Add your background image assets to the project.

You then need to create the background image variable (backgroundImage) and the UIImageView object, and then connect the two. The images will be referenced in the layoutForInterfaceOrientation method which uses the orientation of the device to display the relevant image.

In DocumentPickerViewController.h:

Before other @property elements add:

@property (nonatomic, retain) IBOutlet UIImageView *backgroundImage;

In DocumentPickerViewController.m:

Before other @synthesize elements add:

@synthesize backgroundImage;

Release backgroundImage in dealloc:

- (void)dealloc {
  [backgroundImage release];

Set backgroundImage self to nil in viewDidUnload:

- (void)viewDidUnload {
  self.backgroundImage = nil;
  [super viewDidUnload];

Add links to images in the assets folder in the orientation change method:

- (void)layoutForInterfaceOrientation:(UIInterfaceOrientation)orientation {
  if (UI_USER_INTERFACE_IDIOM() == UIUserInterfaceIdiomPhone) {
    if (UIInterfaceOrientationIsLandscape(orientation)) {
      [docPicker setFrame:CGRectMake(0,5,480,250)];
      [subscriptionButton setFrame:CGRectMake(115,270,110,20)];
      [restoreButton setFrame:CGRectMake(115+110+30,270,110,20)];
      [backgroundImage setImage:[UIImage imageNamed:@"iphone-landscape.png"]];
    else {
      [docPicker setFrame:CGRectMake(0,80,320,250)];
      [subscriptionButton setFrame:CGRectMake(35,370,110,20)];
      [restoreButton setFrame:CGRectMake(35+110+30,370,110,20)];
      [backgroundImage setImage:[UIImage imageNamed:@"iphone-landscape.png"]];
  else {
    if (UIInterfaceOrientationIsLandscape(orientation)) {
      [docPicker setFrame:CGRectMake(0,40,1024,584)];
      [subscriptionButton setFrame:CGRectMake(270,664,222,44)];
      [restoreButton setFrame:CGRectMake(270+222+40,664,222,44)];
      [backgroundImage setImage:[UIImage imageNamed:@"ipad-landscape.png"]];
    else {
      [docPicker setFrame:CGRectMake(0,150,768,584)];
      [subscriptionButton setFrame:CGRectMake(132,830,222,44)];
      [restoreButton setFrame:CGRectMake(132+222+40,830,222,44)];
      [backgroundImage setImage:[UIImage imageNamed:@"ipad-portrait.png"]];

In DocumentPickerView-iPad.xib

Find object library at bottom of right hand toolbar. Create new ‘image view’ element, in the Size Inspector in the toolbar on the right set relevant height and width in either orientation (same dimensions as the images). If the image is full screen x and y should be set to 0. The Autosizing square needs all 6 red lines/arrows toggled on.

To link the image view you just created to the backgroundImage method ensure you have selected the ‘image view’ from the list of elements on the left. In the Connections Inspector (right toolbar) click the circle to the right of ‘New referencing outlet’, hold your mouse down and drag to ‘File’s owner’ in the left toolbar and let go of the mouse. You should see options appear - one of them being backgroundImage - click this to connect the two.

For iPhone do the same in DocumentPickerView-iPhone.xib with the relevant measurements.

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


Powered by Zendesk