VirtualBox

Changeset 55096 in vbox


Ignore:
Timestamp:
Apr 3, 2015 5:51:24 PM (10 years ago)
Author:
vboxsync
Message:

FE/Qt: 7127: Medium-enumeration improvements: UIMedium doxy.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/VBox/Frontends/VirtualBox/src/medium/UIMedium.h

    r52727 r55096  
    44
    55/*
    6  * Copyright (C) 2009-2013 Oracle Corporation
     6 * Copyright (C) 2009-2015 Oracle Corporation
    77 *
    88 * This file is part of VirtualBox Open Source Edition (OSE), as
    … …  
    1515 */
    1616
    17 #ifndef __UIMedium_h__
    18 #define __UIMedium_h__
     17#ifndef ___UIMedium_h___
     18#define ___UIMedium_h___
    1919
    2020/* Qt includes: */
    … …  
    3232#include "iprt/cpp/utils.h"
    3333
    34 /**
    35  * Cache used to override some attributes in the user-friendly "don't show diffs" mode.
    36  */
     34/** Storage medium cache used to
     35  * override some UIMedium attributes in the
     36  * user-friendly "don't show diffs" mode. */
    3737struct NoDiffsCache
    3838{
     39    /** Constructor. */
    3940    NoDiffsCache() : isSet(false), state(KMediumState_NotCreated) {}
     41
     42    /** Operator= reimplementation. */
    4043    NoDiffsCache& operator=(const NoDiffsCache &other)
    4144    {
    … …  
    4750    }
    4851
     52    /** Holds whether the cache is set. */
    4953    bool isSet : 1;
    5054
     55    /** Holds overriden medium state. */
    5156    KMediumState state;
     57    /** Holds overriden medium acquiring result. */
    5258    COMResult result;
     59    /** Holds overriden medium tool-tip. */
    5360    QString toolTip;
    5461};
    5562
    56 /**
    57  * Media descriptor for the GUI.
    58  *
    59  * Maintains the results of the last state (accessibility) check and precomposes
    60  * string parameters such as location, size which can be used in various GUI
    61  * controls.
    62  *
    63  * Many getter methods take the boolean @a aNoDiffs argument. Unless explicitly
    64  * stated otherwise, this argument, when set to @c true, will cause the
    65  * corresponding property of this object's root medium to be returned instead of
    66  * its own one. This is useful when hard disk media is represented in the
    67  * user-friendly "don't show diffs" mode. For non-hard disk media, the value of
    68  * this argument is irrelevant because the root object for such medium is
    69  * the medium itself.
    70  *
    71  * Note that this class "abuses" the KMediumState_NotCreated state value to
    72  * indicate that the accessibility check of the given medium (see
    73  * #blockAndQueryState()) has not been done yet and therefore some parameters
    74  * such as #size() are meaningless because they can be read only from the
    75  * accessible medium. The real KMediumState_NotCreated state is not necessary
    76  * because this class is only used with created (existing) media.
    77  */
     63/** Storage medium descriptor wrapping CMedium wrapper for IMedium interface.
     64  *
     65  * Maintains the results of the last CMedium state (accessibility) check and precomposes
     66  * string parameters such as name, location and size which can be used for various GUI tasks.
     67  *
     68  * Many getter methods take the boolean @a fNoDiffs argument.
     69  * Unless explicitly stated otherwise, this argument, when set to @c true,
     70  * will cause the corresponding property of this object's root medium to be returned instead
     71  * of its own one. This is useful when hard drive medium is reflected in the user-friendly
     72  * "don't show diffs" mode. For non-hard drive mediums, the value of this argument is irrelevant
     73  * because the root object for such medium is the medium itself.
     74  *
     75  * Note that this class "abuses" the KMediumState_NotCreated state value to indicate that the
     76  * accessibility check of the given medium (see #blockAndQueryState()) has not been done yet
     77  * and therefore some parameters such as #size() are meaningless because they can be read only
     78  * from the accessible medium. The real KMediumState_NotCreated state is not necessary because
     79  * this class is only used with created (existing) mediums. */
    7880class UIMedium
    7981{
    8082public:
    8183
    82     /* Default (NULL) constructor:
    83      * Creates NULL uimedium which is not associated with any medium. */
     84    /** Default constructor.
     85      * Creates NULL UIMedium which is not associated with any CMedium. */
    8486    UIMedium();
    8587
    86     /* Lazy wrapping constructor:
    87      * Creates a uimedium associated with the given medium. */
     88    /** Lazy wrapping constructor.
     89      * Creates the UIMedium associated with the given @a medium of the given @a type. */
    8890    UIMedium(const CMedium &medium, UIMediumType type);
    8991
    90     /* Wrapping constructor with known medium state:
    91      * Similar to previous one but sets the uimedium state to passed one.
    92      * Suitable when the medium-state is known such as right after medium creation. */
     92    /** Wrapping constructor with known medium state.
     93      * Similarly to the previous one it creates the UIMedium associated with the
     94      * given @a medium of the given @a type but sets the UIMedium @a state to passed one.
     95      * Suitable when the medium state is known such as right after the medium creation. */
    9396    UIMedium(const CMedium &medium, UIMediumType type, KMediumState state);
    9497
    95     /* Copy-constructor: */
     98    /** Copy constructor.
     99      * Creates the UIMedium on the basis of the passed @a other one. */
    96100    UIMedium(const UIMedium &other);
    97101
    98     /* API: Operator=: */
     102    /** Operator= reimplementation. */
    99103    UIMedium& operator=(const UIMedium &other);
    100104
     105    /** Queries the actual medium state.
     106      * @note This method blocks for the duration of the state check.
     107      *       Since this check may take quite a while,
     108      *       the calling thread must not be the UI thread. */
    101109    void blockAndQueryState();
     110
     111    /** Refreshes the precomposed user-readable strings.
     112      * @note Note that some string such as #size() are meaningless if the medium state is
     113      *       KMediumState_NotCreated (i.e. the medium has not yet been checked for accessibility). */
    102114    void refresh();
    103115
     116    /** Returns whether this medium is hidden.
     117      * @note The medium is considered hidden if it has corresponding
     118      *       medium property or is connected to hidden VMs only. */
    104119    bool isHidden() const { return m_fHidden | m_fAttachedToHiddenMachinesOnly; }
    105120
     121    /** Returns the CMedium wrapped by this UIMedium object. */
    106122    const CMedium &medium() const { return m_medium; }
    107123
     124    /** Returns the type of UIMedium object. */
    108125    UIMediumType type() const { return m_type; }
    109126
    110     /**
    111      * Media state. In "don't show diffs" mode, this is the worst state (in
    112      * terms of inaccessibility) detected on the given hard disk chain.
    113      *
    114      * @param fNoDiffs  @c true to enable user-friendly "don't show diffs" mode.
    115      */
     127    /** Returns the medium state.
     128      * @param fNoDiffs @c true to enable user-friendly "don't show diffs" mode.
     129      * @note  In "don't show diffs" mode, this method returns the worst state
     130      *        (in terms of inaccessibility) detected on the given hard drive chain. */
    116131    KMediumState state(bool fNoDiffs = false) const
    117132    {
    … …  
    120135    }
    121136
     137    /** Returns the error result of the last blockAndQueryState() call. */
    122138    QString lastAccessError() const { return m_strLastAccessError; }
    123139
    124     /**
    125      * Result of the last blockAndQueryState() call. Will indicate an error and
    126      * contain a proper error info if the last state check fails. In "don't show
    127      * diffs" mode, this is the worst result (in terms of inaccessibility)
    128      * detected on the given hard disk chain.
    129      *
    130      * @param fNoDiffs  @c true to enable user-friendly "don't show diffs" mode.
    131      */
     140    /** Returns the result of the last blockAndQueryState() call.
     141      * Indicates an error and contain a proper error info if the last state check fails.
     142      * @param fNoDiffs @c true to enable user-friendly "don't show diffs" mode.
     143      * @note  In "don't show diffs" mode, this method returns the worst result
     144      *        (in terms of inaccessibility) detected on the given hard drive chain. */
    132145    const COMResult &result(bool fNoDiffs = false) const
    133146    {
    … …  
    136149    }
    137150
     151    /** Returns the medium cache key. */
    138152    QString key() const { return m_strKey; }
     153    /** Defines the medium cache @a strKey. */
    139154    void setKey(const QString &strKey) { m_strKey = strKey; }
    140155
     156    /** Returns the medium ID. */
    141157    QString id() const { return m_strId; }
     158
     159    /** Returns the medium name.
     160      * @param fNoDiffs @c true to enable user-friendly "don't show diffs" mode.
     161      * @note  In "don't show diffs" mode, this method returns the name of root in the given hard drive chain. */
    142162    QString name(bool fNoDiffs = false) const { return fNoDiffs ? root().m_strName : m_strName; }
     163    /** Returns the medium location.
     164      * @param fNoDiffs @c true to enable user-friendly "don't show diffs" mode.
     165      * @note  In "don't show diffs" mode, this method returns the location of root in the given hard drive chain. */
    143166    QString location(bool fNoDiffs = false) const { return fNoDiffs ? root().m_strLocation : m_strLocation; }
    144167
     168    /** Returns the medium size.
     169      * @param fNoDiffs @c true to enable user-friendly "don't show diffs" mode.
     170      * @note  In "don't show diffs" mode, this method returns the size of root in the given hard drive chain. */
    145171    QString size(bool fNoDiffs = false) const { return fNoDiffs ? root().m_strSize : m_strSize; }
     172    /** Returns the logical medium size.
     173      * @param fNoDiffs @c true to enable user-friendly "don't show diffs" mode.
     174      * @note  In "don't show diffs" mode, this method returns the logical size of root in the given hard drive chain. */
    146175    QString logicalSize(bool fNoDiffs = false) const { return fNoDiffs ? root().m_strLogicalSize : m_strLogicalSize; }
    147176
     177    /** Returns the hard drive medium disk format.
     178      * @param fNoDiffs @c true to enable user-friendly "don't show diffs" mode.
     179      * @note  In "don't show diffs" mode, this method returns the disk format of root in the given hard drive chain. */
    148180    QString hardDiskFormat(bool fNoDiffs = false) const { return fNoDiffs ? root().m_strHardDiskFormat : m_strHardDiskFormat; }
     181    /** Returns the hard drive medium disk type.
     182      * @param fNoDiffs @c true to enable user-friendly "don't show diffs" mode.
     183      * @note  In "don't show diffs" mode, this method returns the disk type of root in the given hard drive chain. */
    149184    QString hardDiskType(bool fNoDiffs = false) const { return fNoDiffs ? root().m_strHardDiskType : m_strHardDiskType; }
    150185
     186    /** Returns the hard drive medium storage details. */
    151187    QString storageDetails() const { return m_strStorageDetails; }
    152188
     189    /** Returns the medium usage data.
     190      * @param fNoDiffs @c true to enable user-friendly "don't show diffs" mode.
     191      * @note  In "don't show diffs" mode, this method returns the usage data of root in the given hard drive chain. */
    153192    QString usage(bool fNoDiffs = false) const { return fNoDiffs ? root().m_strUsage : m_strUsage; }
     193
     194    /** Returns the short version of medium tool-tip. */
    154195    QString tip() const { return m_strToolTip; }
    155196
     197    /** Returns the medium cache for "don't show diffs" mode. */
    156198    const NoDiffsCache& cache() const { return m_noDiffs; }
    157199
    158     /**
    159      * Returns @c true if this medium is read-only (either because it is
    160      * Immutable or because it has child hard disks). Read-only media can only
    161      * be attached indirectly.
    162      */
     200    /** Returns whether this medium is read-only
     201      * (either because it is Immutable or because it has child hard drives).
     202      * @note Read-only medium can only be attached indirectly. */
    163203    bool isReadOnly() const { return m_fReadOnly; }
    164204
    165     /**
    166      * Returns @c true if this medium is attached to any VM (in the current
    167      * state or in a snapshot) in which case #usage() will contain a string with
    168      * comma-separated VM names (with snapshot names, if any, in parenthesis).
    169      */
     205    /** Returns whether this medium is attached to any VM (in the current state or in a snapshot) in which case
     206      * #usage() will contain a string with comma-separated VM names (with snapshot names, if any, in parenthesis). */
    170207    bool isUsed() const { return !m_strUsage.isNull(); }
    171208
    172     /**
    173      * Returns @c true if this medium is attached to any VM in any snapshot.
    174      */
     209    /** Returns whether this medium is attached to any VM in any snapshot. */
    175210    bool isUsedInSnapshots() const { return m_fUsedInSnapshots; }
    176211
    177     /**
    178      * Returns @c true if this medium corresponds to real host drive.
    179      */
     212    /** Returns whether this medium corresponds to real host drive. */
    180213    bool isHostDrive() const { return m_fHostDrive; }
    181214
    182     /**
    183      * Returns a vector of IDs of all machines this medium is attached to.
    184      */
     215    /** Returns a vector of IDs of all machines this medium is attached to. */
    185216    const QList <QString> &machineIds() const { return m_machineIds; }
    186217
    187     /**
    188      * Returns @c true if this medium is attached to the given machine in the current state.
    189      */
     218    /** Returns whether this medium is attached to the given machine in the current state. */
    190219    bool isAttachedInCurStateTo(const QString &strMachineId) const { return m_curStateMachineIds.indexOf(strMachineId) >= 0; }
    191220
    192     /**
    193      * Returns a vector of IDs of all machines this medium is attached
    194      * to in their current state (i.e. excluding snapshots).
    195      */
     221    /** Returns a vector of IDs of all machines this medium is attached to
     222      * in their current state (i.e. excluding snapshots). */
    196223    const QList <QString> &curStateMachineIds() const { return m_curStateMachineIds; }
    197224
    198     /* API: Parent/Root stuff: */
     225    /** Updates medium parent. */
    199226    void updateParentID();
     227    /** Returns the medium parent ID. */
    200228    QString parentID() const { return m_strParentID; }
     229    /** Returns the medium root ID. */
    201230    QString rootID() const { return m_strRootID; }
     231    /** Returns medium parent. */
    202232    UIMedium parent() const;
     233    /** Returns medium root. */
    203234    UIMedium root() const;
    204235
     236
     237    /** Returns the full version of medium tool-tip.
     238      * @param fNoDiffs     @c true to enable user-friendly "don't show diffs" mode.
     239      * @param fCheckRO     @c true to perform the #readOnly() check and add a notice accordingly.
     240      * @param fNullAllowed @c true to allow NULL medium description to be mentioned in the tool-tip.
     241      * @note  In "don't show diffs" mode (where the attributes of the base hard drive are shown instead
     242      *        of the attributes of the differencing hard drive), extra information will be added to the
     243      *        tooltip to give the user a hint that the medium is actually a differencing hard drive. */
    205244    QString toolTip(bool fNoDiffs = false, bool fCheckRO = false, bool fNullAllowed = false) const;
     245
     246    /** Returns an icon corresponding to the medium state.
     247      * Distinguishes between the Inaccessible state and the situation when querying the state itself failed.
     248      * @param fNoDiffs @c true to enable user-friendly "don't show diffs" mode.
     249      * @param fCheckRO @c true to perform the #readOnly() check and change the icon accordingly.
     250      * @note  In "don't show diffs" mode (where the attributes of the base hard drive are shown instead
     251      *        of the attributes of the differencing hard drive), the most worst medium state on the given
     252      *        hard drive chain will be used to select the medium icon. */
    206253    QPixmap icon(bool fNoDiffs = false, bool fCheckRO = false) const;
    207254
    208     /** Shortcut to <tt>#toolTip(fNoDiffs, true)</tt>. */
     255    /** Shortcut to <tt>#toolTip(fNoDiffs, true, fNullAllowed)</tt>. */
    209256    QString toolTipCheckRO(bool fNoDiffs = false, bool fNullAllowed = false) const { return toolTip(fNoDiffs, true, fNullAllowed); }
    210257
    … …  
    212259    QPixmap iconCheckRO(bool fNoDiffs = false) const { return icon(fNoDiffs, true); }
    213260
    214     QString details(bool fNoDiffs = false, bool fPredictDiff = false, bool aUseHTML = false) const;
     261    /** Returns the details of this medium as a single-line string.
     262      * @param fNoDiffs     @c true to enable user-friendly "don't show diffs" mode.
     263      * @param fPredictDiff @c true to mark the hard drive as differencing if attaching
     264      *                             it would create a differencing hard drive.
     265      * @param fUseHTML     @c true to allow for emphasizing using bold and italics.
     266      * @note  For hard drives, the details include the location, type and the logical size of the hard drive.
     267      *        Note that if @a fNoDiffs is @c true, these properties are queried on the root hard drive of the
     268      *        given hard drive because the primary purpose of the returned string is to be human readable
     269      *        (so that seeing a complex diff hard drive name is usually not desirable).
     270      * @note  For other medium types, the location and the actual size are returned.
     271      *        Arguments @a fPredictDiff and @a fNoDiffs are ignored in this case.
     272      * @note  Use #detailsHTML() instead of passing @c true for @a fUseHTML.
     273      * @note  The medium object may become uninitialized by a third party while this method is reading its properties.
     274      *        In this case, the method will return an empty string. */
     275    QString details(bool fNoDiffs = false, bool fPredictDiff = false, bool fUseHTML = false) const;
    215276
    216277    /** Shortcut to <tt>#details(fNoDiffs, fPredictDiff, true)</tt>. */
    217278    QString detailsHTML(bool fNoDiffs = false, bool fPredictDiff = false) const { return details(fNoDiffs, fPredictDiff, true); }
    218279
    219     /** Returns @c true if this media descriptor is a null object. */
     280    /** Returns @c true if CMedium wrapped by this UIMedium object is a NULL object. */
    220281    bool isNull() const { return m_medium.isNull(); }
    221282
    222     /* Static API: Null medium ID: */
     283    /** Returns NULL medium ID. */
    223284    static QString nullID();
    224285
    225     /** Determines if passed @a medium attached to hidden machines only. */
     286    /** Determines if passed @a medium is attached to hidden machines only. */
    226287    static bool isMediumAttachedToHiddenMachinesOnly(const UIMedium &medium);
    227288
    228289private:
    229290
     291    /** Checks if m_noDiffs is filled in and does it if not.
     292      * @param fNoDiffs @if false, this method immediately returns. */
    230293    void checkNoDiffs(bool fNoDiffs);
    231294
     295    /** Holds the CMedium wrapped by this UIMedium object. */
    232296    CMedium m_medium;
    233297
     298    /** Holds the type of UIMedium object. */
    234299    UIMediumType m_type;
    235300
     301    /** Holds the medium state. */
    236302    KMediumState m_state;
     303    /** Holds the error result of the last blockAndQueryState() call. */
    237304    QString m_strLastAccessError;
     305    /** Holds the result of the last blockAndQueryState() call. */
    238306    COMResult m_result;
    239307
     308    /** Holds the medium cache key. */
    240309    QString m_strKey;
     310    /** Holds the medium ID. */
    241311    QString m_strId;
     312
     313    /** Holds the medium name. */
    242314    QString m_strName;
     315    /** Holds the medium location. */
    243316    QString m_strLocation;
    244317
     318    /** Holds the medium size. */
    245319    QString m_strSize;
     320    /** Holds the medium logical size. */
    246321    QString m_strLogicalSize;
    247322
     323    /** Holds the hard drive medium disk format. */
    248324    QString m_strHardDiskFormat;
     325    /** Holds the hard drive medium disk type. */
    249326    QString m_strHardDiskType;
    250 
     327    /** Holds the hard drive medium storage details. */
    251328    QString m_strStorageDetails;
    252329
     330    /** Holds the medium usage. */
    253331    QString m_strUsage;
     332    /** Holds the medium tool-tip. */
    254333    QString m_strToolTip;
    255334
     335    /** Holds whether this medium is hidden by the corresponding medium property. */
    256336    bool m_fHidden                       : 1;
     337    /** Holds whether this medium is hidden because it's connected to hidden VMs only. */
    257338    bool m_fAttachedToHiddenMachinesOnly : 1;
     339    /** Holds whether this medium is read-only. */
    258340    bool m_fReadOnly                     : 1;
     341    /** Holds whether this medium is attached to any VM in any snapshot. */
    259342    bool m_fUsedInSnapshots              : 1;
     343    /** Holds whether this medium corresponds to real host drive. */
    260344    bool m_fHostDrive                    : 1;
    261345
     346    /** Holds the vector of IDs of all machines this medium is attached to. */
    262347    QList<QString> m_machineIds;
     348    /** Hodls the vector of IDs of all machines this medium is attached to
     349      * in their current state (i.e. excluding snapshots). */
    263350    QList<QString> m_curStateMachineIds;
    264351
     352    /** Holds the medium parent ID. */
    265353    QString m_strParentID;
     354    /** Holds the medium root ID. */
    266355    QString m_strRootID;
    267356
     357    /** Holds the medium cache for "don't show diffs" mode. */
    268358    NoDiffsCache m_noDiffs;
    269359
     360    /** Holds the NULL medium ID. */
    270361    static QString m_sstrNullID;
     362    /** Holds the medium tool-tip table template. */
    271363    static QString m_sstrTable;
     364    /** Holds the medium tool-tip table row template. */
    272365    static QString m_sstrRow;
    273366};
    … …  
    276369typedef QMap<QString, UIMedium> UIMediumMap;
    277370
    278 #endif /* __UIMedium_h__ */
     371#endif /* !___UIMedium_h___ */
Note: See TracChangeset for help on using the changeset viewer.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette