Skip to content

Implementation

Jump to bottom
loktacar edited this page Sep 29, 2012 · 28 revisions

TODO

  • 2.4 Get resolution of all monitors, i.e. implement multi-monitor support, remember the collage plugins
  • Route all plugin selection and usage through the PluginManager class.

Application (1)

wpmaker.py and wpmaker.pyw files (1.1)

These files are executable and start the application.

wpmaker.py (1.1.1)

This executable does the following in order:

  1. Start logging
  2. Initialize PluginManager
  3. Initialize Config class
  4. Find configured UI plugin
  5. Initialize Application and set UI plugin
  6. Start Application

wpmaker.pyw (1.1.2)

This file imports everything from wpmaker.py and calls starts the application the same way. This file is mainly intended for Windows users to start the application without a command prompt (GUI only).

Application class (1.2)

This class handles the main functions of the application. It handles the wallpaper generation thread and calls appropriate plugins for each task. It doesn't consern itself with the Options. It calls methods in the current UI plugin, these are thought of as events.

Instance Variables (1.2.1)

  • self.config: The configuration dictionary.
  • self.logger: The logger currently in use.
  • self.plugin_manager: The PluginManager instance.
  • self.ui: Current UI plugin.
  • self.wallpaper_source: The Wallpaper instance.
  • self.resolution: Current monitor resolution.
  • self.next_generation: Number of seconds from epoch untill next wallpaper generation.
  • self.sleep_increment: Number of seconds between checks of current time and self.next_generation.
  • self.is_paused: True if wallpaper generation is temporarily paused.
  • self.running: Always True while running, loop stops if set to False.
  • self.next_collage_plugin: Name of the Collage plugin class to use henceforth. Used incase UI plugin changes config['collage-plugin'] during generation.

Methods (1.2.2)

  • __init__(self, config, ui=None)

    • config: Configuration dictionary to be used.
    • ui: UI plugin to be used.
    • Initializes Wallpaper class, and sets the neccessary instance variables to begin the loop.

  • get_resolution(self)

    • Returns the value from the appropriate GetResolution plugin.

  • main(self)

    • Runs the loop.

  • pause(self, paused_value=None)

    • paused_value: If set self.paused is set to this value.
    • If paused_value is not passed method will toggle self.paused value.

  • set_wallpaper(self)

    • Calls the set() function of the appropriate SetWallpaper plugin.

  • switch_collage_plugin(self, collage)

    • collage: The name of the Collage plugin to be used next run of the loop.
    • Sets the self.next_collage_plugin to the collage value.

  • ui_hook(self, hook_name, *args, **kwargs)

    • hook_name: Name of the function in the UI plugin's class to be called.
    • *args, **kwargs: Arguments and keyword arguments to be passed on the the appropriate function.
    • Call hook, "event", in the current UI plugin.

Wallpapers class (1.3)

Handles the WallpaperSearch plugins, calling the pop method of a plugin each time the pop method is called.

Instance Variables (1.3.1)

  • self.config: The configuration dictionary.
  • self.logger: The logger currently in use.
  • self.wallpaper_plugins: The WallpaperSearch plugins loaded by the PluginManager.
  • self.plugin_index: The index of the next plugin to be used.

Methods (1.3.2)

  • __init__(self, config)

    • config: Configuration dictionary to be used.
    • Initialized the class.

  • pop(self, count=1)

    • count: Number of images to be popped.
    • Pops images from a single WallpaperSearch plugin.

  • count(self)

    • Returns the number of images currently available in all WallpaperSearch plugins.

Config file (1.4)

This file should only be run once per application instance. It searches folders for configuration files, see AppDirs module for which folders; and uses DocOpt module to read command line options, and print the help message. The options are plugins that inherit the Option class.

Methods (1.4.1)

  • get_config()
    • This method does what is described above. Also this is the only method that should be called by wpmaker.py.

Plugins (2)

Plugins are handled by the PluginManager class implemented in /plugin/__init__.py. When PluginManager is instantiated it searches the /plugin/ folder for subclasses of each of the plugin parent classes, i.e. the plugin types; and stores them in the self.plugins dictionary, the dictionary keys are the names of plugin parent classes. An instance of PluginManager is stored in /plugin/__init__.py as plugin_manager.

The methods below that are not marked Requires implementation are implemented in the plugin parent class.

PluginManager Class (2.1)

Initializes, stores and handles calls to the various plugins.

Instnace Variables (2.1.1)

  • self.logger: The logger currently in use.
  • self.plugins: Dictionary containing the plugins, keys are the names of plugin parent classes.

Methods (2.1.2)

  • __init__(self)
    • Initializes plugins found in the /plugins/ folder.
  • __getitem__(self, key)
    • Returns the value in self.plugins of the same key.
  • set_config(self, config)
    • Since the config is loaded after the plugins, this method sets the config instance variable in those plugins which inherit from the Plugin superclass.
  • find_plugins(self, path, base_class)
    • path: The path which will be searched recursively for plugins.
    • base_class: A list of classes the plugins should inherit from.
    • Searches path for classes which inherit from the classes in base_class.

Collage Plugins (2.2)

Creates a wallpaper collage, popping one or more instances of pygame.Surface from the Wallpaper class and returning a new instance of pygame.Surface, the new wallpaper.

Instance Variables (2.2.1)

  • self.wallpaper_source: The Wallpaper instance currently in use.
  • self.config: The configuration dictionary.
  • self.logger: The logger currently in use.

Methods (2.2.2)

  • __init__(self)
    • Instantiated by PluginManager class. Instance variables set after it's been initialized.
    • Requires implementation, Ex.
    def __init__(self, wallpaper_queue, config):
        super(CollagePluginName, self).__init__(wallpaper_queue, config)
  • generate(self, size)
    • size: Tuple of length 2, (width value, height value).
    • Generate a new wallpaper.
    • Requires implementation, Ex. from SimpleResize plugin.
    wallpapers = self._get_wallpapers()

    self.logger.debug('Generating...')

    collage = pygame.Surface(size)

    wp_offset, wp = self._resize_wallpaper(wallpapers[0], size)

    for x1, x2 in enumerate(range(size[0]), wp_offset[0]):
        for y1, y2 in enumerate(range(size[1]), wp_offset[1]):
            collage.set_at((x2, y2), wp.get_at((x1, y1)))

    self.logger.debug('Generation complete')

    return collage
  • _resize_wallpaper(self, wallpaper, size)
    • wallpaper: pygame.Surface which needs to be resized.
    • size: the new size the wallpaper should take.
    • Resize a pygame.Surface to the desired size. This method returns an offset tuple, (x value, y value), and the resized wallpaper. Cropping is done after resize to speed up the resizing proccess.

Option Plugins (2.3)

Adds arguments to the command line and options in the configuration file. This is the only plugin whose parent class doesn't inherit the Plugin class and so has no self.config dictionary.

Instance variables (2.3.1)

  • self.default: Default value of the opion. A None value means it's required.
  • self.option: The name of the option, used in config file and as the long form command line option.
  • self.cmd_short: Used as the short form command line option.
  • self.cmd_argument: The name of the argument in the command line. A None value (default) means there is no argument.
  • self.description: The description written in the command line when -h or --help is used.
  • self.conf_description: The description written in the sample configuration.
  • self.conf_default: The default value in written in the sample configuration.

Methods (2.3.2)

  • __init__(self)
    • Instantiated by PluginManager class. Instance variables set after it's been initialized.
    • Requires implementation, Ex. from ResolutionOption plugin.
    def __init__(self):
        super(ResolutionOption, self).__init__()

        self.default = self.parse("0x0")
        self.option = 'resolution'
        self.cmd_short = 'r'
        self.cmd_argument = 'RES'
        self.description = 'Forces resolution of generated wallpaper'
        self.conf_description = ['# forces resolution of generated wallpaper\n',
                                 '# i.e. desktop resolution is not queried, useful if\n',
                                 '#   get_resolution plugins fail\n',
                                 '# e.x. setting:\n',
                                 '#   resolution=1680x1050\n']
  • parse(self, value)
    • value: the value to be parsed.
    • Returns an appropriate object instead of the string value.
      • ex. '4' is turned into int(4).
    • Returns value if parse is not implemented.
    • Requires implementation, Ex. from ResolutionOption plugin.
    def parse(self, value):
        res = value.split('x')

        if type(res) == str:
            res = value.split('X')

        return tuple([int(i) for i in res])

Get Resolution Plugins (2.4)

Gets the resolution of all monitors, returns a tuple of monitor resolution tuples.

Instance Variables (2.4.1)

  • self.config: The configuration dictionary.
  • self.logger: The logger currently in use.

Methods (2.4.2)

  • __init__(self)
    • Instantiated by PluginManager class. Instance variables set after it's been initialized.
    • Requires implementation, Ex.
    def __init__(self):
        super(GetResolutionPluginName, self).__init__()
  • platform_check(self)
    • Checks if this plugin is viable on the current platform.
    • Requires implementation
  • get(self)
    • Gets the resolution, returns a tuple of size 2 with the dimensions of the monitor resolution.
    • Requires implementation

Set Wallpaper Plugins (2.5)

Sets the image found in config['wallpaper'] path as the current desktop wallpaper.

Instance Variables (2.5.1)

  • self.config: The configuration dictionary.
  • self.logger: The logger currently in use.

Methods (2.5.1)

  • __init__(self)
    • Instantiated by PluginManager class. Instance variables set after it's been initialized.
    • Requires implementation, Ex.
    def __init__(self):
        super(SetWallpaperPluginName, self).__init__()
  • platform_check(self)
    • Checks if this plugin is viable on the current platform.
    • Requires implementation
  • set(self)
    • Sets the wallpaper.
    • Requires implementation

WallpaperSerach Plugins (2.6)

Searches for new wallpapers, sources could be file system, flickr, instagram, reddit, etc. The Wallpaper class in the app handles calls to these plugins. Images found are kept in the self.wallpapers list. Images need to be saved in the file system to be able to create pygame image instances.

Instance Variables (2.6.1)

  • self.wallpapers: The list of wallpapers available.
  • self.config: The configuration dictionary.
  • self.logger: The logger currently in use.

Methods (2.6.2)

  • __init__(self)
    • Instantiated by PluginManager class. Instance variables set after it's been initialized.
    • Requires implementation, Ex.
    def __init__(self):
        super(WallpaperSearchPluginName, self).__init__()
  • pop(self, count=1)
    • Called by the Wallpaper class when it's pop method is called.
    • Returns a list of pygame.Surface instances.
    • Requires implementation
  • _images_from_path(self, path)
    • Returns a pygame.Surface instance of the image in path.
  • count(self)
    • Returns a count of wallpapers available from this plugin.

UI Plugins (2.7)

Creates a user interface for the application

Instance Variables (2.7.1)

  • self.app: The application instance, set in the Application's __init__ function.
  • self.config: The configuration dictionary.
  • self.logger: The logger currently in use.

Methods (2.7.2)

  • __init__(self)
    • Instantiated by PluginManager class. Instance variables set after it's been initialized. Initializes the ui plugin, the ui itself should be initalized when start_app is called.
    • Requires implementation, Ex.
    def __init__(self):
        super(WallpaperSearchPluginName, self).__init__()

App Control Methods (2.7.2.1)

  • start_app(self)
    • This method starts both the application loop thread and the main thread (the UI thread).
  • exit_app(self)
    • Stops the necessary threads to stop the application running.
  • start_generating(self)
    • Tries to start generating a new collage as soon as possible.

UI Hooks (2.7.2.2)

Plugin events, these hooks are called when certain events happen in the application.

  • app_initialized(self)
    • Called after app has been initialized.
    • UI can be initialized now.
  • app_started(self)
    • Called when main loop is first called.
  • app_quitting(self)
    • Called when the main loop is stopped completely.
  • generate_finished(self)
    • Called when generation of collage is complete.
  • generate_started(self)
    • Called when generation of a collage is starting.
  • wallpaper_search_finished(self)
    • Called after wallpaper search plugin(s) has finished searching.
  • wallpaper_search_started(self)
    • Called when wallpaper search plugin(s) is started.
Clone this wiki locally