Logo Search packages:      
Sourcecode: kdebase-kde4 version File versions  Download package

Profile.h

/*
    This source file is part of Konsole, a terminal emulator.

    Copyright (C) 2006-7 by Robert Knight <robertknight@gmail.com>

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
    02110-1301  USA.
*/

#ifndef PROFILE_H
#define PROFILE_H

// Qt
#include <QtCore/QHash>
#include <QtCore/QObject>
#include <QtCore/QPointer>
#include <QtCore/QStringList>
#include <QtCore/QVariant>

#include <QtGui/QFont>

class KConfigGroup;

namespace Konsole
{

/**
 * Represents a terminal set-up which can be used to 
 * set the initial state of new terminal sessions or applied
 * to existing sessions.  Profiles consist of a number of named
 * properties, which can be retrieved using property() and
 * set using setProperty().  isPropertySet() can be used to check
 * whether a particular property has been set in a profile.
 *
 * Profiles support a simple form of inheritance.  When a new Profile
 * is constructed, a pointer to a parent profile can be passed to
 * the constructor.  When querying a particular property of a profile
 * using property(), the profile will return its own value for that 
 * property if one has been set or otherwise it will return the
 * parent's value for that property.  
 *
 * Profiles can be loaded from disk using ProfileReader instances
 * and saved to disk using ProfileWriter instances.
 *
 * TODO: Profile inherits from QObject so that it can store a guarded 
 * pointer to the parent profile using QPointer<Profile>.  Try to find
 * a more light-weight solution to this.  
 */
00061 class Profile : public QObject 
{
Q_OBJECT

public:
    /**
     * This enum describes the available properties
     * which a Profile may consist of.
     *
     * Properties can be set using setProperty() and read
     * using property()
     */
00073     enum Property
    {
        /** (QString) Path to the profile's configuration file on-disk. */
00076         Path,   

        /** (QString) The descriptive name of this profile. */
00079         Name,   
        /** (QString) Title of this profile that will be displayed. */
00081         Title, 
        /** (QString) The name of the icon associated with this profile.  This 
         * is used in menus and tabs to represent the profile. 
         */
00085         Icon, 
        /** 
         * (QString) The command to execute ( excluding arguments ) when creating a new terminal
         * session using this profile.
         */
00090         Command,   
        /**
         * (QStringList) The arguments which are passed to the program specified by the Command property
         * when creating a new terminal session using this profile.
         */ 
00095         Arguments,
        /** 
         * (QStringList) Additional environment variables ( in the form of NAME=VALUE pairs )
         * which are passed to the program specified by the Command property
         * when creating a new terminal session using this profile. 
         */ 
00101         Environment,
        /** (QString) The initial working directory for sessions created using this profile. */ 
00103         Directory,

        /** (QString) The format used for tab titles when running normal commands. */
00106         LocalTabTitleFormat,   
        /** (QString) The format used for tab titles when the session is running a remote command (eg. SSH) */ 
00108         RemoteTabTitleFormat,   

        /** (bool) Specifies whether the menu bar should be shown in the main application window. */
00111         ShowMenuBar,    
        /** (TabBarModeEnum) Specifies when the tab bar should be shown in the main application window. */ 
00113         TabBarMode,    

        /** (QFont) The font to use in terminal displays using this profile. */
00116         Font,           
        /** (QString) 
         * The name of the color scheme to use in terminal displays using this profile. 
         * Color schemes are managed by the ColorSchemeManager class. 
         */
00121         ColorScheme,   

        /** (QString) The name of the key bindings. 
         * Key bindings are managed by the KeyboardTranslatorManager class. 
         */
00126         KeyBindings, 

        /** (HistoryModeEnum) Specifies the storage type used for keeping the output produced
         * by terminal sessions using this profile.
         */
00131         HistoryMode,
        /** (int) Specifies the number of lines of output to remember in terminal sessions
         * using this profile.  Once the limit is reached, the oldest lines are lost.
         * Only applicable if the HistoryMode property is FixedSizeHistory
         */
00136         HistorySize,
        /**
         * (ScrollBarPositionEnum) Specifies the position of the scroll bar in 
         * terminal displays using this profile.
         */
00141         ScrollBarPosition,  

        /** (bool) Specifies whether text in terminal displays is allowed to blink. */
00144         BlinkingTextEnabled,       
        /** (bool) Specifies whether the flow control keys ( typically Ctrl+S , Ctrl+Q )
         * have any effect.  Also known as Xon/Xoff
         */ 
00148         FlowControlEnabled,
        /** (bool) Specifies whether programs running in the terminal are allowed to 
         * resize the terminal display. 
         */
00152         AllowProgramsToResizeWindow,
        /** (bool) Specifies whether the cursor blinks ( in a manner similar 
         * to text editing applications )
         */
00156         BlinkingCursorEnabled,

        /** (bool) If true, terminal displays use a fixed color to draw the cursor,
         * specified by the CustomCursorColor property.  Otherwise the cursor changes
         * color to match the character underneath it.
         */
00162         UseCustomCursorColor,
        /** (CursorShapeEnum) The shape used by terminal displays to represent the cursor. */ 
00164         CursorShape,           
        /** (QColor) The color used by terminal displays to draw the cursor.  Only applicable
         * if the UseCustomCursorColor property is true. */ 
00167         CustomCursorColor,        

        /** (QString) A string consisting of the characters used to delimit words when
         * selecting text in the terminal display.
         */
00172         WordCharacters,

        /** (TabBarPositionEnum) Position of the tab-bar relative to the terminal displays. */
00175         TabBarPosition,

        /** (String) Default text codec */
00178         DefaultEncoding,

        /** (bool) Whether fonts should be aliased or not */
00181         AntiAliasFonts
    };

    /** 
     * This enum describes the available modes for showing or hiding the tab bar. 
     */
00187     enum TabBarModeEnum
    {
        /** The tab bar is never shown. */
00190         AlwaysHideTabBar   = 0,
        /** The tab bar is shown if there are multiple tabs open or hidden otherwise. */
00192         ShowTabBarAsNeeded = 1,
        /** The tab bar is always shown. */
00194         AlwaysShowTabBar   = 2
    };

    /** 
     * This enum describes the available tab bar positions. 
     */
00200     enum TabBarPositionEnum
    {
        /** Show tab bar below displays. */
00203         TabBarBottom = 0,
        /** Show tab bar above displays. */
00205         TabBarTop    = 1
    };

    /** 
     * This enum describes the modes available to remember lines of output produced 
     * by the terminal. 
     */
00212     enum HistoryModeEnum
    {
        /** No output is remembered.  As soon as lines of text are scrolled off-screen they are lost. */
00215         DisableHistory   = 0,
        /** A fixed number of lines of output are remembered.  Once the limit is reached, the oldest
         * lines are lost. */
00218         FixedSizeHistory = 1,
        /** All output is remembered for the duration of the session.  
         * Typically this means that lines are recorded to
         * a file as they are scrolled off-screen.
         */
00223         UnlimitedHistory = 2
    };

    /**
     * This enum describes the positions where the terminal display's scroll bar may be placed.
     */
00229     enum ScrollBarPositionEnum
    {
        /** Show the scroll-bar on the left of the terminal display. */
00232         ScrollBarLeft   = 0,
        /** Show the scroll-bar on the right of the terminal display. */
00234         ScrollBarRight  = 1,
        /** Do not show the scroll-bar. */
00236         ScrollBarHidden = 2
    };

    /** This enum describes the shapes used to draw the cursor in terminal displays. */
00240     enum CursorShapeEnum
    {
        /** Use a solid rectangular block to draw the cursor. */
00243         BlockCursor     = 0,
        /** Use an 'I' shape, similar to that used in text editing applications, to draw the cursor. */
00245         IBeamCursor     = 1,
        /** Draw a line underneath the cursor's position. */
00247         UnderlineCursor = 2
    };

    /**
     * Constructs a new profile
     */
    Profile(Profile* parent = 0);
    virtual ~Profile() {}

    /** 
     * Changes the parent profile.  When calling the property() method,
     * if the specified property has not been set for this profile,
     * the parent's value for the property will be returned instead.
     */
    void setParent(Profile* parent);

    /** Returns the parent profile. */
    const Profile* parent() const;

    /** 
     * Returns the current value of the specified @p property. 
     *
     * If the specified @p property has not been set in this profile,
     * and a non-null parent was specified in the Profile's constructor,
     * the parent's value for @p property will be returned.
     */
    virtual QVariant property(Property property) const;
    /** Sets the value of the specified @p property to @p value. */
    virtual void setProperty(Property property,const QVariant& value);
    /** Returns true if the specified property has been set in this Profile instance. */
    virtual bool isPropertySet(Property property) const;

    /** Returns a map of the properties set in this Profile instance. */
    virtual QHash<Property,QVariant> setProperties() const;

    /** Returns true if no properties have been set in this Profile instance. */
    bool isEmpty() const;

    /** 
     * Returns true if this is a 'hidden' profile which should not be displayed
     * in menus or saved to disk.
     *
     * This is used for the fallback profile, in case there are no profiles on 
     * disk which can be loaded, or for overlay profiles created to handle
     * command-line arguments which change profile properties.
     */
    bool isHidden() const;

    /** Specifies whether this is a hidden profile.  See isHidden() */
    void setHidden(bool hidden);

    //
    // Convenience methods for property() and setProperty() go here
    //

    /** Convenience method for property(Profile::Path) */
00303     QString path() const { return property(Profile::Path).value<QString>(); }

    /** Convenience method for property(Profile::Name) */
00306     QString name() const { return property(Profile::Name).value<QString>(); }
    
    /** Convenience method for property(Profile::Directory) */
00309     QString defaultWorkingDirectory() const 
            { return property(Profile::Directory).value<QString>(); }

    /** Convenience method for property(Profile::Icon) */
00313     QString icon() const { return property(Profile::Icon).value<QString>(); }

    /** Convenience method for property(Profile::Command) */
00316     QString command() const { return property(Profile::Command).value<QString>(); }

    /** Convenience method for property(Profile::Arguments) */
00319     QStringList arguments() const { return property(Profile::Arguments).value<QStringList>(); }

    /** Convenience method for property(Profile::Font) */
00322     QFont font() const { return property(Profile::Font).value<QFont>(); }

    /** Convenience method for property(Profile::ColorScheme) */
00325     QString colorScheme() const { return property(Profile::ColorScheme).value<QString>(); }

    /** Convenience method for property(Profile::Environment) */
00328     QStringList environment() const { return property(Profile::Environment).value<QStringList>(); }

    /** 
     * Convenience method.
     * Returns the value of the "TERM" value in the environment list.
     */
00334     QString terminal() const { return "xterm"; }

    /**
     * Returns true if @p name has been associated with an element
     * from the Property enum or false otherwise.
     */
    static bool isNameRegistered(const QString& name);

    /** 
     * Returns the element from the Property enum associated with the 
     * specified @p name.
     *
     * @param The name of the property to look for, this is case insensitive.
     */
    static Property lookupByName(const QString& name);
    /**
     * Returns the string names associated with the specified @p property from
     * the Property enum, in the order the associations were created using
     * registerName()
     */
    static QList<QString> namesForProperty(Property property);

    /** 
     * Returns the primary name for the specified @p property.
     * TODO More documentation
     */
    static QString primaryNameForProperty(Property property);

    /**
     * Adds an association between a string @p name and a @p property.
     * Subsequent calls to lookupByName() with @p name as the argument
     * will return @p property.
     */
    static void registerName(Property property , const QString& name); 

private:
    // fills the table with default names for profile properties
    // the first time it is called.
    // subsequent calls return immediately
    static void fillTableWithDefaultNames();

    QHash<Property,QVariant> _propertyValues;
    QPointer<Profile> _parent;

    bool _hidden;

    static QHash<QString,Property> _propertyByName;
    static QHash<Property,QString> _nameByProperty;
    struct PropertyNamePair
    {
        Property property;
        const char* name;
    };
    static const PropertyNamePair DefaultPropertyNames[];
};

/** 
 * A profile which contains a number of default settings for various properties.
 * This can be used as a parent for other profiles or a fallback in case
 * a profile cannot be loaded from disk.
 */
00395 class FallbackProfile : public Profile
{
public:
    FallbackProfile();
};

/** Interface for all classes which can load profile settings from a file. */
00402 class ProfileReader
{
public:
    virtual ~ProfileReader() {}
    /** Returns a list of paths to profiles which this reader can read. */
00407     virtual QStringList findProfiles() { return QStringList(); }
    /** 
     * Attempts to read a profile from @p path and 
     * save the property values described into @p profile.
     *
     * Returns true if the profile was successfully read or false otherwise.
     *
     * @param path Path to the profile to read
     * @param profile Pointer to the Profile the settings will be read into
     * @param parentProfile Receives the name of the parent profile specified in
     */
    virtual bool readProfile(const QString& path , Profile* profile , QString& parentProfile) = 0;
};
/** Reads a KDE 3 profile .desktop file. */
00421 class KDE3ProfileReader : public ProfileReader
{
public:
    virtual QStringList findProfiles();
    virtual bool readProfile(const QString& path , Profile* profile, QString& parentProfile);
};
/** Reads a KDE 4 .profile file. */
00428 class KDE4ProfileReader : public ProfileReader
{
public:
    virtual QStringList findProfiles();
    virtual bool readProfile(const QString& path , Profile* profile, QString& parentProfile);
private:
    template <typename T>
    void readStandardElement(const KConfigGroup& group , 
                             Profile* info , 
                             Profile::Property property);
};
/** Interface for all classes which can write profile settings to a file. */
00440 class ProfileWriter
{
public:
    virtual ~ProfileWriter() {}
    /** 
     * Returns a suitable path-name for writing 
     * @p profile to. The path-name should be accepted by
     * the corresponding ProfileReader class.
     */
    virtual QString getPath(const Profile* profile) = 0;
    /**
     * Writes the properties and values from @p profile to the file specified by
     * @p path.  This profile should be readable by the corresponding ProfileReader class.
     */
    virtual bool writeProfile(const QString& path , const Profile* profile) = 0;
};
/** Writes a KDE 4 .profile file. */
00457 class KDE4ProfileWriter : public ProfileWriter
{
public:
    virtual QString getPath(const Profile* profile);
    virtual bool writeProfile(const QString& path , const Profile* profile);

private:
    void writeStandardElement(KConfigGroup& group,
                              const Profile* profile,
                              Profile::Property property);
};

/** 
 * Parses an input string consisting of property names
 * and assigned values and returns a table of properties
 * and values.
 *
 * The input string will typically look like this:
 *
 * @code
 *   PropertyName=Value;PropertyName=Value ...
 * @endcode 
 *
 * For example:
 *
 * @code
 *   Icon=konsole;Directory=/home/bob
 * @endcode
 */
00486 class ProfileCommandParser
{
public:
    /**
     * Parses an input string consisting of property names
     * and assigned values and returns a table of 
     * properties and values.
     */
    QHash<Profile::Property,QVariant> parse(const QString& input);

};

}

#endif // PROFILE_H

Generated by  Doxygen 1.6.0   Back to index