Updated documentation and coding standards for ControlList. Fixes #3959. (dc1887ce) · Commits · aflab / astrogeology / ISIS3

isis/src/qisis/objs/ControlList/ControlList.cpp

+178 −8

Original line number	Diff line number	Diff line
		@@ -37,7 +37,6 @@
		#include "Color.h"
		#include "FileName.h"
		#include "IException.h"
		#include "IString.h"
		#include "Project.h"
		#include "XmlStackedHandlerReader.h"

		@@ -103,6 +102,8 @@ namespace Isis {
		/**
		* Create an control list from a list of control net file names. This is slow (serial) and not
		* recommended.
		*
		* @param fileNames Control net file names
		*/
		ControlList::ControlList(QStringList &fileNames) {
		foreach (QString fileName, fileNames) {
		@@ -125,6 +126,10 @@ namespace Isis {


		/**
		* Appends a control pointer to the control list
		*
		* @param value The control pointer to append
		*
		* @see QList<Control *>::append()
		*/
		void ControlList::append(Control * const &value) {
		@@ -134,6 +139,10 @@ namespace Isis {


		/**
		* Appends a list of control pointers to the control list
		*
		* @param value The list of control pointers to append
		*
		* @see QList<Control *>::append()
		*/
		void ControlList::append(const QList<Control *> &value) {
		@@ -143,6 +152,8 @@ namespace Isis {


		/**
		* Clears the control list
		*
		* @see QList<Control *>::clear()
		*/
		void ControlList::clear() {
		@@ -155,6 +166,12 @@ namespace Isis {


		/**
		* Erases a control pointer from the control list at the specified position
		*
		* @param pos The position to erase at
		*
		* @return @b QList<Control *>::iterator Iterator to the next item in the list
		*
		* @see QList<Control *>::erase()
		*/
		QList<Control *>::iterator ControlList::erase(iterator pos) {
		@@ -165,6 +182,13 @@ namespace Isis {


		/**
		* Erases all control pointers starting at "begin" up to (but not including) end
		*
		* @param begin Iterator to the first control pointer to erase from the list
		* @param end Iterator to the end control pointer (which will not be erased)
		*
		* @return @b QList<Control *>::iterator Iterator to the end control pointer
		*
		* @see QList<Control *>::erase()
		*/
		QList<Control *>::iterator ControlList::erase(iterator begin, iterator end) {
		@@ -175,6 +199,11 @@ namespace Isis {


		/**
		* Inserts a control pointer at the specified position in the control list
		*
		* @param i The index to insert at
		* @param value The control pointer to insert
		*
		* @see QList<Control *>::insert()
		*/
		void ControlList::insert(int i, Control * const &value) {
		@@ -185,6 +214,13 @@ namespace Isis {


		/**
		* Inserts a control pointer before the specified iterator position
		*
		* @param before Iterator to the item to insert the control pointer before
		* @param value The control pointer to insert
		*
		* @return @b QList<Control *>::iterator Iterator to the inserted control pointer
		*
		* @see QList<Control *>::insert()
		*/
		QList<Control >::iterator ControlList::insert(iterator before, Control const &value) {
		@@ -195,6 +231,10 @@ namespace Isis {


		/**
		* Prepends a control pointer to the control list
		*
		* @param value The control pointer to prepend to the control list
		*
		* @see QList<Control *>::prepend()
		*/
		void ControlList::prepend(Control * const &value) {
		@@ -204,6 +244,11 @@ namespace Isis {


		/**
		* Equivalent to append(value)
		*
		* @param value The control pointer to append to the control list
		*
		* @see ControlList::append(Control * const &value)
		* @see QList<Control *>::push_back()
		*/
		void ControlList::push_back(Control * const &value) {
		@@ -213,6 +258,11 @@ namespace Isis {


		/**
		* Equivalent to prepend(value)
		*
		* @param value The control pointer to prepend to the control list
		*
		* @see ControlList::prepend(Control * const &value)
		* @see QList<Control *>::push_front()
		*/
		void ControlList::push_front(Control * const &value) {
		@@ -222,6 +272,12 @@ namespace Isis {


		/**
		* Removes all occurences of the control pointer in the control list
		*
		* @param value The control pointer value to remove
		*
		* @return @b int The number of control pointers removed
		*
		* @see QList<Control *>::removeAll()
		*/
		int ControlList::removeAll(Control * const &value) {
		@@ -236,6 +292,10 @@ namespace Isis {


		/**
		* Removes the control pointer at the specified index
		*
		* @param i The index of the control pointer to remove
		*
		* @see QList<Control *>::removeAt()
		*/
		void ControlList::removeAt(int i) {
		@@ -245,6 +305,8 @@ namespace Isis {


		/**
		* Removes the first control pointer from the control list
		*
		* @see QList<Control *>::removeFirst()
		*/
		void ControlList::removeFirst() {
		@@ -254,6 +316,8 @@ namespace Isis {


		/**
		* Removes the last control pointer from the control list
		*
		* @see QList<Control *>::removeLast()
		*/
		void ControlList::removeLast() {
		@@ -263,6 +327,12 @@ namespace Isis {


		/**
		* Removes the first occurence of the control pointer from the control list
		*
		* @param value The control pointer to remove
		*
		* @return @b bool True if a control pointer was removed; otherwise false
		*
		* @see QList<Control *>::removeOne()
		*/
		bool ControlList::removeOne(Control * const &value) {
		@@ -277,6 +347,10 @@ namespace Isis {


		/**
		* Swaps this control list's control pointers with the other list of control pointers
		*
		* @param other The list of control pointers to swap
		*
		* @see QList<Control *>::swap()
		*/
		void ControlList::swap(QList<Control *> &other) {
		@@ -289,6 +363,12 @@ namespace Isis {


		/**
		* Remove the control pointer at the specified index and returns it
		*
		* @param i The index of the control pointer to take
		*
		* @return @b Contol * The removed control pointer
		*
		* @see QList<Control *>::takeAt()
		*/
		Control *ControlList::takeAt(int i) {
		@@ -299,6 +379,10 @@ namespace Isis {


		/**
		* Removes the first control pointer from the control list and returns it
		*
		* @return @b Control * The first control pointer in the control list
		*
		* @see QList<Control *>::takeFirst()
		*/
		Control *ControlList::takeFirst() {
		@@ -309,6 +393,10 @@ namespace Isis {


		/**
		* Removes the last control pointer from the control list and returns it
		*
		* @return @b Control * The last control pointer in the control list
		*
		* @see QList<Control *>::takeLast()
		*/
		Control *ControlList::takeLast() {
		@@ -319,6 +407,12 @@ namespace Isis {


		/**
		* Appends control pointers from the other list to this control list
		*
		* @param The list of other control pointers to append
		*
		* @return @b ControlList & Reference to this control list
		*
		* @see QList<Control *>::operator+=()
		*/
		ControlList &ControlList::operator+=(const QList<Control *> &other) {
		@@ -333,6 +427,12 @@ namespace Isis {


		/**
		* Appends a control pointer to this control list
		*
		* @param other The control pointer to append
		*
		* @return @b ControlList & Reference to this control list
		*
		* @see QList<Control *>::operator+=()
		*/
		ControlList &ControlList::operator+=(Control * const &other) {
		@@ -343,6 +443,12 @@ namespace Isis {


		/**
		* Appends a list of other control pointers to this control list
		*
		* @param other The list of other control pointers to append
		*
		* @return @b ControlList & Reference to this control list
		*
		* @see QList<Control *>::operator<<()
		*/
		ControlList &ControlList::operator<<(const QList<Control *> &other) {
		@@ -357,6 +463,12 @@ namespace Isis {


		/**
		* Appends a control pointer to this control list
		*
		* @param other The control pointer to append
		*
		* @return @b ControlList & Reference to this control list
		*
		* @see QList<Control *>::operator<<()
		*/
		ControlList &ControlList::operator<<(Control * const &other) {
		@@ -367,6 +479,12 @@ namespace Isis {


		/**
		* Assigns another list of control pointers to this control list
		*
		* @param rhs The other list of control pointers to assign
		*
		* @return @b ControlList & Reference to this control list
		*
		* @see QList<Control *>::operator=()
		*/
		ControlList &ControlList::operator=(const QList<Control *> &rhs) {
		@@ -385,7 +503,10 @@ namespace Isis {
		* Assignment operator
		*
		* @param rhs The right hand side of the '=' operator
		* @return *this
		*
		* @return @b ControlList & Reference to this ControlList
		*
		* @see ControlList::operator=(const QList<Control *> &rhs)
		*/
		ControlList &ControlList::operator=(const ControlList &rhs) {
		bool countChanging = (rhs.count() != count());
		@@ -427,7 +548,7 @@ namespace Isis {
		/**
		* Get the human-readable name of this control list
		*
		* @return The name of the control list (or an empty string if anonymous).
		* @return @b QString The name of the control list (or an empty string if anonymous).
		*/
		QString ControlList::name() const {
		return m_name;
		@@ -438,7 +559,7 @@ namespace Isis {
		* Get the path to these controls in the control list (relative to project root). This only
		* applies to a control list from the project.
		*
		* @return The path to the controls in the control list (or an empty string if unknown).
		* @return @b QString The path to the controls in the control list (or an empty string if unknown).
		*/
		QString ControlList::path() const {
		return m_path;
		@@ -446,7 +567,11 @@ namespace Isis {


		/**
		* Delete all of the contained Controls from disk (see Control::deleteFromDisk())
		* Delete all of the contained Controls from disk
		*
		* @param project Project to delete controls from
		*
		* @see Control::deleteFromDisk()
		*/
		void ControlList::deleteFromDisk(Project *project) {
		foreach (Control control, this) {
		@@ -477,6 +602,13 @@ namespace Isis {
		* ...
		* </controls>
		* </pre>
		*
		* @param stream XML stream that contains the control list data
		* @param project Project to save control list from
		* @param newProjectRoot Filename root to save control list to
		*
		* @throws IException::Io "Unable Failed to create directory"
		* @throws IException::Io "Unable to save control information, could not be opened for writing"
		*/
		void ControlList::save(QXmlStreamWriter &stream, const Project *project, FileName newProjectRoot)
		const {
		@@ -550,6 +682,12 @@ namespace Isis {
		}


		/**
		* CopyControlDataFunctor constructor.
		*
		* @param project Project to copy from
		* @param newProjectRoot Project to copy to
		*/
		ControlList::CopyControlDataFunctor::CopyControlDataFunctor(const Project *project,
		FileName newProjectRoot) {
		m_project = project;
		@@ -557,22 +695,42 @@ namespace Isis {
		}


		/**
		* CopyControlDataFunctor copy constructor.
		*
		* @param other The other CopyControlDataFunctor to initialize data from
		*/
		ControlList::CopyControlDataFunctor::CopyControlDataFunctor(const CopyControlDataFunctor &other) {
		m_project = other.m_project;
		m_newProjectRoot = other.m_newProjectRoot;
		}


		/**
		* CopyControlDataFunctor destructor
		*/
		ControlList::CopyControlDataFunctor::~CopyControlDataFunctor() {
		}


		/**
		* Copies the Control from one project to another.
		*
		* @param controlToCopy The Control to copy
		*/
		void ControlList::CopyControlDataFunctor::operator()(Control const &controlToCopy) {
		controlToCopy->copyToNewProjectRoot(m_project, m_newProjectRoot);
		return NULL;
		}


		/**
		* CopyControlDataFunctor assignment operator.
		*
		* @param rhs The other CopyControlDataFunctor to copy from
		*
		* @return @b ControlList::CopyControlDataFunctor The new copy
		*/
		ControlList::CopyControlDataFunctor &ControlList::CopyControlDataFunctor::operator=(
		const CopyControlDataFunctor &rhs) {
		m_project = rhs.m_project;
		@@ -582,7 +740,7 @@ namespace Isis {


		/**
		* Create an XML Handler (reader) that can populate the ControlList class data. See
		* Create an XML Handler (reader/writer) that can populate the ControlList class data. See
		* ControlList::save() for the expected format.
		*
		* @param controlList The control list we're going to be initializing
		@@ -598,7 +756,12 @@ namespace Isis {
		* Handle an XML start element. This expects <controlList/> and <control/> elements (it reads both
		* the project XML and the controls.xml file).
		*
		* @return If we should continue reading the XML (usually true).
		* @param namespaceURI ???
		* @param localName The keyword name given to the member variable in the XML
		* @param qName ???
		* @param atts The attribute containing the keyword value given for the given localName
		*
		* @return @b bool If we should continue reading the XML (usually true).
		*/
		bool ControlList::XmlHandler::startElement(const QString &namespaceURI, const QString &localName,
		const QString &qName, const QXmlAttributes &atts) {
		@@ -629,7 +792,14 @@ namespace Isis {
		* Handle an XML end element. This handles <controlList /> by opening and reading the controls.xml
		* file.
		*
		* @return If we should continue reading the XML (usually true).
		* @param namespaceURI ???
		* @param localName The keyword name given to the member variable in the XML
		* @param qName ???
		*
		* @return @b bool If we should continue reading the XML (usually true).
		*
		* @throws IException::Io "Unable to open with read access"
		* @throws IException::Io "Failed to open control list XML"
		*/
		bool ControlList::XmlHandler::endElement(const QString &namespaceURI, const QString &localName,
		const QString &qName) {

isis/src/qisis/objs/ControlList/ControlList.h

+17 −9

Original line number	Diff line number	Diff line
		@@ -2,9 +2,9 @@
		#define ControlList_H

		#include <QDebug>
		#include <QObject>
		#include <QList>
		#include <QMetaType>
		#include <QObject>

		#include "Control.h"
		#include "ControlDisplayProperties.h"
		@@ -19,7 +19,9 @@ namespace Isis {
		class XmlStackedHandlerReader;

		/**
		* Adapted from ImageList
		* Maintains a list of Controls so that control nets can easily be copied from one Project to
		* another, saved to disk, or deleted from disk. Overrides several common QList methods for
		* managing a list of Controls as well. Adapted from ImageList
		*
		* @author 2012-09-01 Tracie Sucharski
		*
		@@ -27,6 +29,7 @@ namespace Isis {
		* @history 2012-09-01 Tracie Sucharski - Original version.
		* @history 2015-10-14 Jeffrey Covington - Declared ControlList * as a Qt
		* metatype for use with QVariant.
		* @history 2016-06-06 Ian Humphrey - Updated documentation and coding standards. Fixes #3959.
		*/
		class ControlList : public QObject, public QList<Control *> {
		Q_OBJECT
		@@ -36,8 +39,8 @@ namespace Isis {
		ControlList(QString name, QString path, QObject *parent = NULL);
		explicit ControlList(QObject *parent = NULL);
		explicit ControlList(QList<Control >, QObject parent = NULL);
		explicit ControlList(Project *project,
		XmlStackedHandlerReader xmlReader, QObject parent = NULL);
		explicit ControlList(Project project, XmlStackedHandlerReader xmlReader,
		QObject *parent = NULL);
		explicit ControlList(QStringList &);
		ControlList(const ControlList &);
		~ControlList();
		@@ -121,11 +124,16 @@ namespace Isis {
		CopyControlDataFunctor &operator=(const CopyControlDataFunctor &rhs);

		private:
		const Project *m_project;
		FileName m_newProjectRoot;
		const Project *m_project; //!< Project to copy the control list to
		FileName m_newProjectRoot; //!< The filename of the destination project's root
		};

		/**
		* Nested class used to write the ControlList object information to an XML file for the
		* purposes of saving an restoring the state of the object.
		*
		* @see ControlList::save for the expected format
		*
		* @author 2012-09-27 Tracie Sucharski - Adapted from ImageList::XmlHandler
		*
		* @internal
		@@ -143,13 +151,13 @@ namespace Isis {
		private:
		Q_DISABLE_COPY(XmlHandler);

		ControlList *m_controlList;
		Project *m_project;
		ControlList *m_controlList; //!< Control list to be read or written
		Project *m_project; //!< Project that contains the control list
		};


		private:
		QString m_name;
		QString m_name; //!< Name of the ControlList

		/**
		* This stores the directory name that contains the controls in this control list.