CCP4i Task Window Style Guide

Liz Potterton

The Task in Context

Understand the context in which a program is used:
  • talk to program authors and expert users
  • look at scripts

    • Design the interface to do the whole 'task' rather than run an individual program.

    Ensure users will not need to do file format conversions on input or output files.

    Present the task and the options within the tasks in terms of what goal is achieved.
    (Existing task names like 'Run Refmac' do not do this!)

    Sensible Defaults

    For the most common usage of a task a user should only need to select files (and MTZ columns) and provide non-default data.
    If a task has several popular modes then these should be presented as a menu (at the top of the window) and after the user has selected the mode then all defaults should be appropriate for that mode.  (This may mean having two variables with different defaults for one input parameter.)

    Rules for Customising the Task Window

    When a user selects a particular mode or option the task window should be customised for that option - nothing irrelevant to that option should be visible.
    A mode or option should only control the visibility of widgets that are further down the task window.
    A stricter rule is that a mode or option should only control the visibility of widgets in the same folder except:
    A mode/option in the Protocol folder can change anything in the window.
    Only a mode/option in the Protocol folder should affect the visibility of whole folders.

    Overall Folder Layout

    General scheme is: Protocol, Files, 'Frequently Used Options', folders for specific aspects, 'Infrequently Used Options' (a ragbag).
    The 'Frequently Used' options may relate to completely different aspects of the task but they are the set of options that a novice user ought to think about.
    All other options should be grouped into folders for specific subject areas with a clear folder title.  Ideally these folders should be closed.
    A ragbag of 'Infrequently Used' options is occasionally necessary.

    What Goes in the Protocol Folder?

    There is no clearcut distinction between 'Protocol' and 'Frequently Used'.

    The rules for customising the task window mean that any option which changes the input/output files or visibility of whole folders should go in the Protocol folder.

    "Do I have to do something here?"

    This is the most confusing thing about interfaces for a user.

    Compulsory input should be indicated by the contrast gold colour.  (-oblig option to CreateLine).

     The way some programs work is that they determine the required mode of action based on the input MTZ columns - it is not acceptable to carry over this approach to the GUI! The user should choose what they want to do in the protocol folder and only the necessary column label selection should be visible.

    Layout of 'Complex' Data

    For example the definitions of heavy atom in heavy atom refinement.  Ideally all of the information that a user might want to view and edit at one time should be in one folder and not spread throughout the task window.

    Help Facilities

    Do:-
  • Use the message option to give *extra* information about an input.  Also include the command file keywords(s), if appropriate, as (KEYWORD) at the end of the message line.
  • Use the target option  to provide a link to further information.
  • Write GUI specific documentation which probably should be more novice-oriented than program documentation.  But, it should also have a section, for the benefit of experts, explaining what a complex run script is doing - particularly if it is running subsidiary, utility programs.

    • Fine Tuning

    Expect to have to revise the GUI in the light of input from users.  Get prototype version of GUI tested by experts and users.
     

    Task Window Names

    Task window names should be the same as the task name on the menus (this ought to be enforced automatically!).